@isdk/mdast-plus 0.1.2 → 0.2.0

package/README.cn.md

@@ -11,7 +11,7 @@
 ## 特性
 
 - **Fluent API**: 链式调用接口 `mdast(input).use(plugin).toHTML()`。
-- **分阶段插件**: 将转换组织为 `normalize`、`compile` 和 `finalize` 阶段，支持优先级排序。
+- **分阶段插件**: 将转换组织为 `parse`, `normalize`, `compile`, `finalize` 和 `stringify` 阶段。
 - **语义化规范**:
   - **指令 (Directives)**: 规范化提示框 (Admonition) 名称并从标签中提取标题。
   - **表格跨行/跨列**: 支持 HTML 输出中的 `rowspan` 和 `colspan`。
@@ -40,6 +40,17 @@ const html = await mdast(':::warning[重要提示]\n请小心！\n:::')
 // 结果: <div title="重要提示" class="warning"><p>请小心！</p></div>
 ```
 
+### 配置输入选项
+
+您可以通过 `.from()` 的第二个参数向输入插件（如 `remark-gfm` 或 `remark-parse`）传递选项：
+
+```typescript
+// 启用单个波浪线删除线 (~text~)
+const md = await mdast('Hello ~world~')
+  .from('markdown', { remarkGfm: { singleTilde: true } })
+  .toMarkdown();
+```
+
 ### 图片尺寸
 
 ```typescript
@@ -50,23 +61,46 @@ const html = await mdast('![Cat](cat.png#=500x300)').toHTML();
 ### AST 输出
 
 ```typescript
+// 获取处理后的完整 AST (在 normalization 之后)
 const ast = await mdast('==高亮内容==').toAST();
-// 返回 mdast Root 对象
+
+// 获取原始 AST (在 parse 之后, normalization 之前)
+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' })
-  .use({
-    name: 'my-plugin',
-    stage: 'compile',
-    transform: async (tree) => {
-      // 转换 AST
-    }
-  })
+  // 以数组形式在 'compile' 阶段添加多个插件
+  .use([pluginA, pluginB])
+  // 或在特定阶段添加一组插件
+  .useAt('parse', htmlReadabilityPlugins)
+  .priority(10) // 比默认插件更晚执行
   .to('html');
+
+console.log(vfile.value); // 序列化后的 HTML 字符串
+```
+
+### 插件行为
+
+`mdast-plus` 内部使用 [unified](https://github.com/unifiedjs/unified)。如果您多次添加同一个插件函数，最后的配置将**覆盖**之前的配置。
+
+```typescript
+// 插件将只执行一次，且选项为: 2
+pipeline.use(myPlugin, { option: 1 });
+pipeline.use(myPlugin, { option: 2 });
+```
+
+若要多次运行相同的插件逻辑（例如用于不同目的），请提供不同的函数引用：
+
+```typescript
+// 插件将执行两次
+pipeline.use(myPlugin, { option: 1 });
+pipeline.use(myPlugin.bind({}), { option: 2 });
 ```
 
 ### 任意格式支持
@@ -74,16 +108,20 @@ const { content, assets } = await mdast(myInput)
 您可以注册自定义的输入或输出格式：
 
 ```typescript
-import { FluentProcessor, mdast } from '@isdk/mdast-plus';
+import { MdastPipeline, mdast, PipelineStage } from '@isdk/mdast-plus';
 
 // 注册自定义输出格式
-FluentProcessor.registerFormat('reverse', {
-  stringify: (p) => {
-    p.Compiler = (tree) => {
-      // 您的自定义序列化逻辑
-      return '...';
-    };
-  }
+MdastPipeline.register({
+  id: 'reverse',
+  output: [{
+    plugin: function() {
+      this.Compiler = (tree) => {
+        // 您的自定义序列化逻辑
+        return '...';
+      };
+    },
+    stage: PipelineStage.stringify
+  }]
 });
 
 const result = await mdast('Hello').to('reverse');
@@ -93,11 +131,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.  **normalize** (order 0-100): 清理并规范化树。
-2.  **compile** (order 0-100): 高级语义转换。
-3.  **finalize** (order 0-100): 输出前的最后准备。
+> **注意**: 每个阶段只允许存在一个主插件。如果多个插件被标记为 main，则只有最后定义的那个会作为替换生效。
 
 ## 内置核心插件
 
@@ -108,6 +154,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

@@ -11,7 +11,7 @@ English | [简体中文](./README.cn.md) | [GitHub](https://github.com/isdk/mdas
 ## Features
 
 - **Fluent API**: Chainable interface `mdast(input).use(plugin).toHTML()`.
-- **Staged Plugins**: Organize transformations into `normalize`, `compile`, and `finalize` stages with priority ordering.
+- **Staged Plugins**: Organize transformations into `parse`, `normalize`, `compile`, `finalize`, and `stringify` stages.
 - **Semantic Normalization**:
   - **Directives**: Canonicalizes admonition names and extracts titles from labels.
   - **Table Spans**: Support for `rowspan` and `colspan` in HTML output.
@@ -40,6 +40,17 @@ const html = await mdast(':::warning[Special Note]\nBe careful!\n:::')
 // Result: <div title="Special Note" class="warning"><p>Be careful!</p></div>
 ```
 
+### Configure Input Options
+
+You can pass options to input plugins (like `remark-gfm` or `remark-parse`) using the second argument of `.from()`:
+
+```typescript
+// Enable single tilde strikethrough (~text~)
+const md = await mdast('Hello ~world~')
+  .from('markdown', { remarkGfm: { singleTilde: true } })
+  .toMarkdown();
+```
+
 ### Image Sizing
 
 ```typescript
@@ -50,23 +61,46 @@ const html = await mdast('![Cat](cat.png#=500x300)').toHTML();
 ### AST Output
 
 ```typescript
+// Get the fully processed AST (after normalization)
 const ast = await mdast('==Highlighted==').toAST();
-// Returns the mdast Root object
+
+// Get the raw AST (after parsing, before normalization)
+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' })
-  .use({
-    name: 'my-plugin',
-    stage: 'compile',
-    transform: async (tree) => {
-      // transform the AST
-    }
-  })
+  // 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.
+
+```typescript
+// The plugin will run ONCE with option: 2
+pipeline.use(myPlugin, { option: 1 });
+pipeline.use(myPlugin, { option: 2 });
+```
+
+To run the same plugin logic multiple times (e.g., for different purposes), provide a distinct function reference:
+
+```typescript
+// The plugin will run TWICE
+pipeline.use(myPlugin, { option: 1 });
+pipeline.use(myPlugin.bind({}), { option: 2 });
 ```
 
 ### Arbitrary Formats
@@ -74,16 +108,20 @@ const { content, assets } = await mdast(myInput)
 You can register custom input or output formats:
 
 ```typescript
-import { FluentProcessor, mdast } from '@isdk/mdast-plus';
+import { MdastPipeline, mdast, PipelineStage } from '@isdk/mdast-plus';
 
 // Register a custom output format
-FluentProcessor.registerFormat('reverse', {
-  stringify: (p) => {
-    p.Compiler = (tree) => {
-      // your custom stringification logic
-      return '...';
-    };
-  }
+MdastPipeline.register({
+  id: 'reverse',
+  output: [{
+    plugin: function() {
+      this.Compiler = (tree) => {
+        // your custom stringification logic
+        return '...';
+      };
+    },
+    stage: PipelineStage.stringify
+  }]
 });
 
 const result = await mdast('Hello').to('reverse');
@@ -93,11 +131,19 @@ 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.
+3.  **compile** (200): High-level semantic transformations.
+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.
 
-1.  **normalize** (order 0-100): Cleanup and canonicalize the tree.
-2.  **compile** (order 0-100): High-level semantic transformations.
-3.  **finalize** (order 0-100): Final preparation before output.
+> **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
 
@@ -108,6 +154,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