@isdk/mdast-plus 0.1.2 → 0.1.3

package/docs/_media/CONTRIBUTING.md

@@ -8,11 +8,13 @@ Thank you for your interest in contributing to `@isdk/mdast-plus`! This document
 
 ### Core Concepts
 
-1.  **Fluent API**: The main entry point is the `mdast()` function in `src/pipeline.ts`.
-2.  **Staged Plugins**: Plugins are categorized into three stages:
+1.  **Fluent API**: The main entry point is the `mdast()` function in `src/pipeline.ts`, backed by `MdastPipeline`.
+2.  **Staged Plugins**: Plugins are categorized into 5 stages (`PipelineStage`):
+    *   `parse`: Parsing input to AST.
     *   `normalize`: Cleanup and canonicalize the tree.
     *   `compile`: High-level semantic transformations.
     *   `finalize`: Final preparation before output.
+    *   `stringify`: Serializing AST to output.
 3.  **Universal Data Protocols**: Nodes use `node.data` for metadata, and `node.data.hProperties` for HTML attributes.
 
 ## Getting Started
@@ -55,39 +57,58 @@ pnpm run lint
 ## Adding a New Plugin
 
 1.  Create your plugin in `src/plugins/`.
-2.  Implement the `MdastPlugin` interface:
+2.  Implement the `MdastPlugin` interface. The `plugin` property should be a standard unified plugin.
 
 ```typescript
-import { MdastPlugin } from '../types';
+import { MdastPlugin, PipelineStage } from '../types';
+import { visit } from 'unist-util-visit';
+
+const myUnifiedPlugin = (options) => {
+  return (tree) => {
+    visit(tree, 'text', (node) => {
+      // transform logic
+    });
+  };
+};
 
 export const myPlugin: MdastPlugin = {
-  name: 'my-plugin',
-  stage: 'normalize', // 'normalize' | 'compile' | 'finalize'
+  plugin: myUnifiedPlugin,
+  stage: PipelineStage.normalize, // or 'compile', 'finalize'
   order: 50,          // 0-100
-  transform: async (tree, processor) => {
-    // Visit nodes and transform the tree
-  }
 };
 ```
 
-3.  Register your plugin in `src/pipeline.ts` in the `FluentProcessor` constructor if it should be a default plugin.
+3.  If it's a default plugin, add it to the `input` or `output` list of the relevant format in `src/formats/`.
 
 ## Adding a New Format
 
-1. Implement the `MdastFormatDefinition` interface.
-2. Register it using `FluentProcessor.registerFormat(name, definition)`.
+1. Define a `MdastFormat` object.
+2. Register it using `MdastPipeline.register(format)`.
 
 ```typescript
-import { FluentProcessor } from '../pipeline';
-
-FluentProcessor.registerFormat('json', {
-  stringify: (processor) => {
-    processor.Compiler = (tree) => JSON.stringify(tree);
-  }
+import { MdastPipeline, PipelineStage } from '../src/pipeline';
+
+MdastPipeline.register({
+  id: 'json',
+  title: 'JSON Format',
+  output: [{
+    plugin: function() {
+      this.Compiler = (tree) => JSON.stringify(tree);
+    },
+    stage: PipelineStage.stringify
+  }]
 });
 ```
 
 > **Note**: Format names are case-insensitive.
+>
+> **Important**: `unified` requires a `Compiler` to be attached for the process to complete successfully. If your format is intended to return an object (like the AST itself) rather than a string, you must provide a "pass-through" compiler:
+>
+> ```typescript
+> function astCompiler() {
+>   this.Compiler = (tree) => tree;
+> }
+> ```
 
 ## Coding Standards
 

package/docs/_media/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,8 +61,11 @@ 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' });
 ```
 
 ### 高级工作流
@@ -59,31 +73,49 @@ const ast = await mdast('==高亮内容==').toAST();
 ```typescript
 const { content, assets } = await mdast(myInput)
   .data({ myGlobal: 'value' })
-  .use({
-    name: 'my-plugin',
-    stage: 'compile',
-    transform: async (tree) => {
-      // 转换 AST
-    }
-  })
+  // 在 'compile' 阶段添加自定义插件
+  .useAt('compile', myPlugin, { option: 1 })
+  .priority(10) // 比默认插件更晚执行
   .to('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 });
+```
+
 ### 任意格式支持
 
 您可以注册自定义的输入或输出格式：
 
 ```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');
@@ -95,9 +127,11 @@ const result = await mdast('Hello').to('reverse');
 
 插件根据它们的 `stage` (阶段) 和 `order` (顺序) 执行：
 
-1.  **normalize** (order 0-100): 清理并规范化树。
-2.  **compile** (order 0-100): 高级语义转换。
-3.  **finalize** (order 0-100): 输出前的最后准备。
+1.  **parse** (0): 输入解析 (例如 `remark-parse`)。
+2.  **normalize** (100): 清理并规范化树。
+3.  **compile** (200): 高级语义转换。
+4.  **finalize** (300): 输出前的最后准备 (例如 `rehype-sanitize`)。
+5.  **stringify** (400): 输出生成。
 
 ## 内置核心插件
 

package/docs/classes/MdastBasePipeline.md

@@ -0,0 +1,348 @@
+[**@isdk/mdast-plus**](../README.md)
+
+***
+
+[@isdk/mdast-plus](../globals.md) / MdastBasePipeline
+
+# Class: MdastBasePipeline
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:26](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L26)
+
+Base implementation of the fluent mdast processing pipeline.
+Manages the plugin registry and the execution queue.
+
+## Extended by
+
+- [`MdastPipeline`](MdastPipeline.md)
+
+## Constructors
+
+### Constructor
+
+> **new MdastBasePipeline**(`input`): `MdastBasePipeline`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:53](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L53)
+
+Initializes a new pipeline instance with the given input.
+
+#### Parameters
+
+##### input
+
+`Compatible`
+
+Content to process (string, Buffer, VFile, or AST Node).
+
+#### Returns
+
+`MdastBasePipeline`
+
+## Properties
+
+### input
+
+> `protected` **input**: `Compatible`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:46](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L46)
+
+***
+
+### queue
+
+> `protected` **queue**: [`MdastPlugin`](../interfaces/MdastPlugin.md)[] = `[]`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:47](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L47)
+
+## Methods
+
+### assembleProcessor()
+
+> `protected` **assembleProcessor**(`queue`): `Processor`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:254](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L254)
+
+Assembles a unified processor based on the sorted plugin queue.
+
+#### Parameters
+
+##### queue
+
+[`MdastPlugin`](../interfaces/MdastPlugin.md)[]
+
+#### Returns
+
+`Processor`
+
+***
+
+### ensureInputPlugins()
+
+> `protected` **ensureInputPlugins**(`queue`, `overrides?`, `maxStage?`): `void`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:123](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L123)
+
+Ensures that input plugins (parser, normalizers) are present in the queue.
+Adds implicit plugins if no parser is detected.
+
+#### Parameters
+
+##### queue
+
+[`MdastPlugin`](../interfaces/MdastPlugin.md)[]
+
+##### overrides?
+
+`Record`\<`string`, `any`\>
+
+##### maxStage?
+
+[`PipelineStage`](../enumerations/PipelineStage.md) = `PipelineStage.stringify`
+
+#### Returns
+
+`void`
+
+***
+
+### from()
+
+> **from**(`fmt`, `overrides?`): `this`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:152](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L152)
+
+Configures the input format and adds its associated plugins to the pipeline.
+
+#### Parameters
+
+##### fmt
+
+Format ID or definition.
+
+`string` | [`MdastFormat`](../interfaces/MdastFormat.md)
+
+##### overrides?
+
+`Record`\<`string`, `any`\>
+
+Optional map to override plugin options by plugin name.
+
+#### Returns
+
+`this`
+
+The pipeline instance for chaining.
+
+***
+
+### getFormat()
+
+> **getFormat**(`id`): `undefined` \| [`MdastFormat`](../interfaces/MdastFormat.md)
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:60](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L60)
+
+Instance-level access to the global format registry.
+
+#### Parameters
+
+##### id
+
+`string`
+
+#### Returns
+
+`undefined` \| [`MdastFormat`](../interfaces/MdastFormat.md)
+
+***
+
+### priority()
+
+> **priority**(`order`): `this`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:242](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L242)
+
+Sets the priority order for the most recently added plugin.
+Plugins with lower order run earlier within the same stage.
+
+#### Parameters
+
+##### order
+
+`number`
+
+Numeric priority.
+
+#### Returns
+
+`this`
+
+The pipeline instance for chaining.
+
+***
+
+### to()
+
+> **to**(`fmt`, `overrides?`): `Promise`\<`VFile`\>
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:172](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L172)
+
+Processes the pipeline and serializes the result into the specified format.
+
+#### Parameters
+
+##### fmt
+
+Target format ID or definition.
+
+`string` | [`MdastFormat`](../interfaces/MdastFormat.md)
+
+##### overrides?
+
+`Record`\<`string`, `any`\>
+
+Optional map to override plugin options.
+
+#### Returns
+
+`Promise`\<`VFile`\>
+
+A promise resolving to a VFile containing the result.
+
+***
+
+### toRuntimeEntry()
+
+> `protected` **toRuntimeEntry**(`entry`, `defaultStage`, `overrides?`): [`MdastPlugin`](../interfaces/MdastPlugin.md) & `object`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:84](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L84)
+
+Normalizes a plugin entry for runtime execution.
+
+#### Parameters
+
+##### entry
+
+[`MdastPlugin`](../interfaces/MdastPlugin.md)
+
+##### defaultStage
+
+[`PipelineStage`](../enumerations/PipelineStage.md)
+
+##### overrides?
+
+`Record`\<`string`, `any`\>
+
+#### Returns
+
+[`MdastPlugin`](../interfaces/MdastPlugin.md) & `object`
+
+***
+
+### use()
+
+> **use**(`plugin`, ...`options`): `this`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:215](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L215)
+
+Adds a plugin to the pipeline's compile stage.
+
+#### Parameters
+
+##### plugin
+
+`any`
+
+The unified plugin function.
+
+##### options
+
+...`any`[]
+
+Arguments for the plugin.
+
+#### Returns
+
+`this`
+
+The pipeline instance for chaining.
+
+***
+
+### useAt()
+
+> **useAt**(`stage`, `plugin`, ...`options`): `this`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:226](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L226)
+
+Adds a plugin to the pipeline at a specific stage.
+
+#### Parameters
+
+##### stage
+
+The stage name or numeric value.
+
+`"parse"` | `"normalize"` | `"compile"` | `"finalize"` | `"stringify"`
+
+##### plugin
+
+`any`
+
+The unified plugin function.
+
+##### options
+
+...`any`[]
+
+Arguments for the plugin.
+
+#### Returns
+
+`this`
+
+The pipeline instance for chaining.
+
+***
+
+### getFormat()
+
+> `static` **getFormat**(`id`): `undefined` \| [`MdastFormat`](../interfaces/MdastFormat.md)
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:42](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L42)
+
+Retrieves a registered format by its ID.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The format identifier.
+
+#### Returns
+
+`undefined` \| [`MdastFormat`](../interfaces/MdastFormat.md)
+
+The format definition or undefined if not found.
+
+***
+
+### register()
+
+> `static` **register**(`format`): `void`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:33](https://github.com/isdk/mdast-plus.js/blob/bacb4922529058fef775e3f4b4e71c98ac1cab17/src/pipeline.ts#L33)
+
+Registers a global document format.
+
+#### Parameters
+
+##### format
+
+[`MdastFormat`](../interfaces/MdastFormat.md)
+
+The format definition to register.
+
+#### Returns
+
+`void`