@isdk/mdast-plus 0.1.3 → 0.2.1

package/README.cn.md

@@ -71,18 +71,26 @@ const rawAst = await mdast('==高亮内容==').toAST({ stage: 'parse' });
 ### 高级工作流
 
 ```typescript
-const { content, assets } = await mdast(myInput)
+import { htmlReadabilityPlugins } from '@isdk/mdast-plus';
+
+const vfile = await mdast(myInput)
   .data({ myGlobal: 'value' })
-  // 在 'compile' 阶段添加自定义插件
-  .useAt('compile', myPlugin, { option: 1 })
+  // 以数组形式在 'compile' 阶段添加多个插件
+  .use([pluginA, pluginB])
+  // 或在特定阶段添加一组插件
+  .useAt('parse', htmlReadabilityPlugins)
   .priority(10) // 比默认插件更晚执行
   .to('html');
+
+console.log(vfile.value); // 序列化后的 HTML 字符串
 ```
 
 ### 插件行为
 
 `mdast-plus` 内部使用 [unified](https://github.com/unifiedjs/unified)。如果您多次添加同一个插件函数，最后的配置将**覆盖**之前的配置。
 
+> **警告**: 将 `false` 作为插件选项传递（例如 `.use(myPlugin, false)`）将**完全禁用**该插件。对于普通插件，这意味着它们将不会运行。对于标记为 `main: true` 的插件（如默认解析器的替代者），如果它们被 `false` 禁用，它们将**不会**替换该阶段的默认插件，从而安全地回退到默认行为。如果你需要跳过插件逻辑但保持其激活状态（例如为了保留其解析器），请改用选项对象，例如 `{ enable: false }`。
+
 ```typescript
 // 插件将只执行一次，且选项为: 2
 pipeline.use(myPlugin, { option: 1 });
@@ -125,13 +133,19 @@ const result = await mdast('Hello').to('reverse');
 
 ## 分阶段处理
 
-插件根据它们的 `stage` (阶段) 和 `order` (顺序) 执行：
+插件根据它们的 `stage` (阶段)、`order` (顺序) 以及语义约束 (`before`/`after`) 执行：
+
+1. **parse** (0): 输入解析 (例如 `remark-parse`)。
+2. **normalize** (100): 清理并规范化树。
+3. **compile** (200): 高级语义转换。
+4. **finalize** (300): 输出前的最后准备 (例如 `rehype-sanitize`)。
+5. **stringify** (400): 输出生成。
+
+### 主插件替换 (Main Plugin Replacement)
+
+每个阶段可以有一个“主”插件。如果一个插件被标记为 `main: true`，它将 **替换** 该阶段中的第一个插件。这对于在保持管道其余部分不变的情况下更换默认解析器或编译器非常有用。
 
-1.  **parse** (0): 输入解析 (例如 `remark-parse`)。
-2.  **normalize** (100): 清理并规范化树。
-3.  **compile** (200): 高级语义转换。
-4.  **finalize** (300): 输出前的最后准备 (例如 `rehype-sanitize`)。
-5.  **stringify** (400): 输出生成。
+> **注意**: 每个阶段只允许存在一个主插件。如果多个插件被标记为 main，则只有最后定义的那个会作为替换生效。
 
 ## 内置核心插件
 
@@ -142,6 +156,7 @@ const result = await mdast('Hello').to('reverse');
 | `extract-code-meta` | normalize | 从代码块元数据中解析 `title="foo"`。 |
 | `image-size` | normalize | 从图片 URL 中解析 `#=WxH`。 |
 | `normalize-inline-styles` | normalize | 标准化 `==mark==`、`~sub~` 和 `^sup^`。 |
+| `html-readability` | parse | 使用 Mozilla 的 Readability 从 HTML 中提取主体内容。使用 `htmlReadabilityPlugins` 数组可以简化配置。 |
 
 ## 贡献
 

package/README.md

@@ -71,18 +71,26 @@ const rawAst = await mdast('==Highlighted==').toAST({ stage: 'parse' });
 ### Advanced Pipeline
 
 ```typescript
-const { content, assets } = await mdast(myInput)
+import { htmlReadabilityPlugins } from '@isdk/mdast-plus';
+
+const vfile = await mdast(myInput)
   .data({ myGlobal: 'value' })
-  // Add a custom plugin at the 'compile' stage
-  .useAt('compile', myPlugin, { option: 1 })
+  // Add multiple plugins as an array at the 'compile' stage
+  .use([pluginA, pluginB])
+  // Or add a set of plugins at a specific stage
+  .useAt('parse', htmlReadabilityPlugins)
   .priority(10) // Run later than default plugins
   .to('html');
+
+console.log(vfile.value); // The serialized HTML string
 ```
 
 ### Plugin Behavior
 
 `mdast-plus` uses [unified](https://github.com/unifiedjs/unified) internally. If you add the same plugin function multiple times, the last configuration **overrides** the previous ones.
 
+> **Warning**: Passing `false` as a plugin option (e.g., `.use(myPlugin, false)`) will **disable** the plugin entirely. For regular plugins, this means they simply won't run. For plugins marked as `main: true` (like replacements for the default parser), if they are disabled with `false`, they will **not** replace the default plugin of that stage, providing a safe fallback to the default behavior. If you want to bypass a plugin's logic while keeping it active (e.g. to maintain its parser), use an options object like `{ enable: false }` instead.
+
 ```typescript
 // The plugin will run ONCE with option: 2
 pipeline.use(myPlugin, { option: 1 });
@@ -125,7 +133,7 @@ const result = await mdast('Hello').to('reverse');
 
 ## Staged Processing
 
-Plugins are executed based on their `stage` and `order`:
+Plugins are executed based on their `stage`, `order`, and semantic constraints (`before`/`after`):
 
 1.  **parse** (0): Input parsing (e.g., `remark-parse`).
 2.  **normalize** (100): Cleanup and canonicalize the tree.
@@ -133,6 +141,12 @@ Plugins are executed based on their `stage` and `order`:
 4.  **finalize** (300): Final preparation before output (e.g. `rehype-sanitize`).
 5.  **stringify** (400): Output generation.
 
+### Main Plugin Replacement
+
+Each stage can have one "main" plugin. If a plugin is marked with `main: true`, it will **replace** the first plugin in that same stage. This is useful for swapping out default parsers or compilers while keeping the rest of the pipeline intact.
+
+> **Note**: Only one main plugin is allowed per stage. If multiple plugins are marked as main, only the last one defined will take effect as the replacement.
+
 ## Core Plugins Included
 
 | Plugin | Stage | Description |
@@ -142,6 +156,7 @@ Plugins are executed based on their `stage` and `order`:
 | `extract-code-meta` | normalize | Parses `title="foo"` from code block meta. |
 | `image-size` | normalize | Parses `#=WxH` from image URLs. |
 | `normalize-inline-styles` | normalize | Standardizes `==mark==`, `~sub~`, and `^sup^`. |
+| `html-readability` | parse | Uses Mozilla's Readability to extract main content from HTML. Use `htmlReadabilityPlugins` array for easier setup. |
 
 ## Contributing