@isdk/mdast-plus 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/README.cn.md +62 -19
  2. package/README.md +62 -19
  3. package/dist/index.d.mts +192 -125
  4. package/dist/index.d.ts +192 -125
  5. package/dist/index.js +1 -1
  6. package/dist/index.mjs +1 -1
  7. package/docs/README.md +62 -19
  8. package/docs/_media/CONTRIBUTING.md +39 -18
  9. package/docs/_media/README.cn.md +62 -19
  10. package/docs/classes/MdastBasePipeline.md +348 -0
  11. package/docs/classes/MdastPipeline.md +531 -0
  12. package/docs/enumerations/PipelineStage.md +62 -0
  13. package/docs/functions/astCompiler.md +25 -0
  14. package/docs/functions/jsonParser.md +24 -0
  15. package/docs/functions/mdast.md +4 -4
  16. package/docs/globals.md +17 -10
  17. package/docs/interfaces/MdastDataOrigin.md +8 -8
  18. package/docs/interfaces/MdastFormat.md +71 -0
  19. package/docs/interfaces/MdastMark.md +4 -4
  20. package/docs/interfaces/MdastPlugin.md +27 -27
  21. package/docs/interfaces/MdastSub.md +4 -4
  22. package/docs/interfaces/MdastSup.md +4 -4
  23. package/docs/type-aliases/PipelineStageName.md +13 -0
  24. package/docs/variables/DefaultPipelineStage.md +13 -0
  25. package/docs/variables/astFormat.md +15 -0
  26. package/docs/variables/htmlFormat.md +16 -0
  27. package/docs/variables/markdownFormat.md +16 -0
  28. package/package.json +11 -9
  29. package/docs/classes/FluentProcessor.md +0 -194
  30. package/docs/functions/htmlFormat.md +0 -24
  31. package/docs/functions/markdownFormat.md +0 -24
  32. package/docs/interfaces/ConvertResult.md +0 -39
  33. package/docs/interfaces/MdastAsset.md +0 -41
  34. package/docs/interfaces/MdastFormatDefinition.md +0 -51
  35. package/docs/interfaces/MdastReader.md +0 -41
  36. package/docs/interfaces/MdastTransformer.md +0 -33
  37. package/docs/interfaces/MdastWriter.md +0 -47
  38. package/docs/type-aliases/Stage.md +0 -13
package/README.cn.md CHANGED
@@ -11,12 +11,13 @@
11
11
  ## 特性
12
12
 
13
13
  - **Fluent API**: 链式调用接口 `mdast(input).use(plugin).toHTML()`。
14
- - **分阶段插件**: 将转换组织为 `normalize`、`compile` 和 `finalize` 阶段,支持优先级排序。
14
+ - **分阶段插件**: 将转换组织为 `parse`, `normalize`, `compile`, `finalize` 和 `stringify` 阶段。
15
15
  - **语义化规范**:
16
16
  - **指令 (Directives)**: 规范化提示框 (Admonition) 名称并从标签中提取标题。
17
17
  - **表格跨行/跨列**: 支持 HTML 输出中的 `rowspan` 和 `colspan`。
18
18
  - **代码元数据**: 对代码块元数据字符串进行结构化解析。
19
19
  - **图片尺寸**: 支持 URL 糖语法 (例如 `image.png#=500x300`) 来设置图片尺寸。
20
+ - **行内样式**: 内置对 `==高亮==`、`~下标~` 和 `^上标^` 的支持。
20
21
  - **深度类型支持**: 基于 TypeScript 构建,完整支持 unist/mdast 的模块扩充。
21
22
 
22
23
  ## 安装
@@ -39,6 +40,17 @@ const html = await mdast(':::warning[重要提示]\n请小心!\n:::')
39
40
  // 结果: <div title="重要提示" class="warning"><p>请小心!</p></div>
40
41
  ```
41
42
 
43
+ ### 配置输入选项
44
+
45
+ 您可以通过 `.from()` 的第二个参数向输入插件(如 `remark-gfm` 或 `remark-parse`)传递选项:
46
+
47
+ ```typescript
48
+ // 启用单个波浪线删除线 (~text~)
49
+ const md = await mdast('Hello ~world~')
50
+ .from('markdown', { remarkGfm: { singleTilde: true } })
51
+ .toMarkdown();
52
+ ```
53
+
42
54
  ### 图片尺寸
43
55
 
44
56
  ```typescript
@@ -46,36 +58,64 @@ const html = await mdast('![Cat](cat.png#=500x300)').toHTML();
46
58
  // 结果: <img src="cat.png" alt="Cat" width="500" height="300">
47
59
  ```
48
60
 
61
+ ### AST 输出
62
+
63
+ ```typescript
64
+ // 获取处理后的完整 AST (在 normalization 之后)
65
+ const ast = await mdast('==高亮内容==').toAST();
66
+
67
+ // 获取原始 AST (在 parse 之后, normalization 之前)
68
+ const rawAst = await mdast('==高亮内容==').toAST({ stage: 'parse' });
69
+ ```
70
+
49
71
  ### 高级工作流
50
72
 
51
73
  ```typescript
52
74
  const { content, assets } = await mdast(myInput)
53
75
  .data({ myGlobal: 'value' })
54
- .use({
55
- name: 'my-plugin',
56
- stage: 'compile',
57
- transform: async (tree) => {
58
- // 转换 AST
59
- }
60
- })
76
+ // 在 'compile' 阶段添加自定义插件
77
+ .useAt('compile', myPlugin, { option: 1 })
78
+ .priority(10) // 比默认插件更晚执行
61
79
  .to('html');
62
80
  ```
63
81
 
82
+ ### 插件行为
83
+
84
+ `mdast-plus` 内部使用 [unified](https://github.com/unifiedjs/unified)。如果您多次添加同一个插件函数,最后的配置将**覆盖**之前的配置。
85
+
86
+ ```typescript
87
+ // 插件将只执行一次,且选项为: 2
88
+ pipeline.use(myPlugin, { option: 1 });
89
+ pipeline.use(myPlugin, { option: 2 });
90
+ ```
91
+
92
+ 若要多次运行相同的插件逻辑(例如用于不同目的),请提供不同的函数引用:
93
+
94
+ ```typescript
95
+ // 插件将执行两次
96
+ pipeline.use(myPlugin, { option: 1 });
97
+ pipeline.use(myPlugin.bind({}), { option: 2 });
98
+ ```
99
+
64
100
  ### 任意格式支持
65
101
 
66
102
  您可以注册自定义的输入或输出格式:
67
103
 
68
104
  ```typescript
69
- import { FluentProcessor, mdast } from '@isdk/mdast-plus';
105
+ import { MdastPipeline, mdast, PipelineStage } from '@isdk/mdast-plus';
70
106
 
71
107
  // 注册自定义输出格式
72
- FluentProcessor.registerFormat('reverse', {
73
- stringify: (p) => {
74
- p.Compiler = (tree) => {
75
- // 您的自定义序列化逻辑
76
- return '...';
77
- };
78
- }
108
+ MdastPipeline.register({
109
+ id: 'reverse',
110
+ output: [{
111
+ plugin: function() {
112
+ this.Compiler = (tree) => {
113
+ // 您的自定义序列化逻辑
114
+ return '...';
115
+ };
116
+ },
117
+ stage: PipelineStage.stringify
118
+ }]
79
119
  });
80
120
 
81
121
  const result = await mdast('Hello').to('reverse');
@@ -87,9 +127,11 @@ const result = await mdast('Hello').to('reverse');
87
127
 
88
128
  插件根据它们的 `stage` (阶段) 和 `order` (顺序) 执行:
89
129
 
90
- 1. **normalize** (order 0-100): 清理并规范化树。
91
- 2. **compile** (order 0-100): 高级语义转换。
92
- 3. **finalize** (order 0-100): 输出前的最后准备。
130
+ 1. **parse** (0): 输入解析 (例如 `remark-parse`)。
131
+ 2. **normalize** (100): 清理并规范化树。
132
+ 3. **compile** (200): 高级语义转换。
133
+ 4. **finalize** (300): 输出前的最后准备 (例如 `rehype-sanitize`)。
134
+ 5. **stringify** (400): 输出生成。
93
135
 
94
136
  ## 内置核心插件
95
137
 
@@ -99,6 +141,7 @@ const result = await mdast('Hello').to('reverse');
99
141
  | `normalize-table-span` | normalize | 将表格单元格跨度迁移到 `hProperties`。 |
100
142
  | `extract-code-meta` | normalize | 从代码块元数据中解析 `title="foo"`。 |
101
143
  | `image-size` | normalize | 从图片 URL 中解析 `#=WxH`。 |
144
+ | `normalize-inline-styles` | normalize | 标准化 `==mark==`、`~sub~` 和 `^sup^`。 |
102
145
 
103
146
  ## 贡献
104
147
 
package/README.md CHANGED
@@ -11,12 +11,13 @@ English | [简体中文](./README.cn.md) | [GitHub](https://github.com/isdk/mdas
11
11
  ## Features
12
12
 
13
13
  - **Fluent API**: Chainable interface `mdast(input).use(plugin).toHTML()`.
14
- - **Staged Plugins**: Organize transformations into `normalize`, `compile`, and `finalize` stages with priority ordering.
14
+ - **Staged Plugins**: Organize transformations into `parse`, `normalize`, `compile`, `finalize`, and `stringify` stages.
15
15
  - **Semantic Normalization**:
16
16
  - **Directives**: Canonicalizes admonition names and extracts titles from labels.
17
17
  - **Table Spans**: Support for `rowspan` and `colspan` in HTML output.
18
18
  - **Code Meta**: Structured parsing of code block metadata strings.
19
19
  - **Image Sizing**: URL "sugar" support (e.g., `image.png#=500x300`) for image dimensions.
20
+ - **Inline Styles**: Built-in support for `==Highlight==`, `~Subscript~`, and `^Superscript^`.
20
21
  - **Deeply Typed**: Built on TypeScript with full support for unist/mdast module augmentation.
21
22
 
22
23
  ## Installation
@@ -39,6 +40,17 @@ const html = await mdast(':::warning[Special Note]\nBe careful!\n:::')
39
40
  // Result: <div title="Special Note" class="warning"><p>Be careful!</p></div>
40
41
  ```
41
42
 
43
+ ### Configure Input Options
44
+
45
+ You can pass options to input plugins (like `remark-gfm` or `remark-parse`) using the second argument of `.from()`:
46
+
47
+ ```typescript
48
+ // Enable single tilde strikethrough (~text~)
49
+ const md = await mdast('Hello ~world~')
50
+ .from('markdown', { remarkGfm: { singleTilde: true } })
51
+ .toMarkdown();
52
+ ```
53
+
42
54
  ### Image Sizing
43
55
 
44
56
  ```typescript
@@ -46,36 +58,64 @@ const html = await mdast('![Cat](cat.png#=500x300)').toHTML();
46
58
  // Result: <img src="cat.png" alt="Cat" width="500" height="300">
47
59
  ```
48
60
 
61
+ ### AST Output
62
+
63
+ ```typescript
64
+ // Get the fully processed AST (after normalization)
65
+ const ast = await mdast('==Highlighted==').toAST();
66
+
67
+ // Get the raw AST (after parsing, before normalization)
68
+ const rawAst = await mdast('==Highlighted==').toAST({ stage: 'parse' });
69
+ ```
70
+
49
71
  ### Advanced Pipeline
50
72
 
51
73
  ```typescript
52
74
  const { content, assets } = await mdast(myInput)
53
75
  .data({ myGlobal: 'value' })
54
- .use({
55
- name: 'my-plugin',
56
- stage: 'compile',
57
- transform: async (tree) => {
58
- // transform the AST
59
- }
60
- })
76
+ // Add a custom plugin at the 'compile' stage
77
+ .useAt('compile', myPlugin, { option: 1 })
78
+ .priority(10) // Run later than default plugins
61
79
  .to('html');
62
80
  ```
63
81
 
82
+ ### Plugin Behavior
83
+
84
+ `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.
85
+
86
+ ```typescript
87
+ // The plugin will run ONCE with option: 2
88
+ pipeline.use(myPlugin, { option: 1 });
89
+ pipeline.use(myPlugin, { option: 2 });
90
+ ```
91
+
92
+ To run the same plugin logic multiple times (e.g., for different purposes), provide a distinct function reference:
93
+
94
+ ```typescript
95
+ // The plugin will run TWICE
96
+ pipeline.use(myPlugin, { option: 1 });
97
+ pipeline.use(myPlugin.bind({}), { option: 2 });
98
+ ```
99
+
64
100
  ### Arbitrary Formats
65
101
 
66
102
  You can register custom input or output formats:
67
103
 
68
104
  ```typescript
69
- import { FluentProcessor, mdast } from '@isdk/mdast-plus';
105
+ import { MdastPipeline, mdast, PipelineStage } from '@isdk/mdast-plus';
70
106
 
71
107
  // Register a custom output format
72
- FluentProcessor.registerFormat('reverse', {
73
- stringify: (p) => {
74
- p.Compiler = (tree) => {
75
- // your custom stringification logic
76
- return '...';
77
- };
78
- }
108
+ MdastPipeline.register({
109
+ id: 'reverse',
110
+ output: [{
111
+ plugin: function() {
112
+ this.Compiler = (tree) => {
113
+ // your custom stringification logic
114
+ return '...';
115
+ };
116
+ },
117
+ stage: PipelineStage.stringify
118
+ }]
79
119
  });
80
120
 
81
121
  const result = await mdast('Hello').to('reverse');
@@ -87,9 +127,11 @@ const result = await mdast('Hello').to('reverse');
87
127
 
88
128
  Plugins are executed based on their `stage` and `order`:
89
129
 
90
- 1. **normalize** (order 0-100): Cleanup and canonicalize the tree.
91
- 2. **compile** (order 0-100): High-level semantic transformations.
92
- 3. **finalize** (order 0-100): Final preparation before output.
130
+ 1. **parse** (0): Input parsing (e.g., `remark-parse`).
131
+ 2. **normalize** (100): Cleanup and canonicalize the tree.
132
+ 3. **compile** (200): High-level semantic transformations.
133
+ 4. **finalize** (300): Final preparation before output (e.g. `rehype-sanitize`).
134
+ 5. **stringify** (400): Output generation.
93
135
 
94
136
  ## Core Plugins Included
95
137
 
@@ -99,6 +141,7 @@ Plugins are executed based on their `stage` and `order`:
99
141
  | `normalize-table-span` | normalize | Migrates table cell spans to `hProperties`. |
100
142
  | `extract-code-meta` | normalize | Parses `title="foo"` from code block meta. |
101
143
  | `image-size` | normalize | Parses `#=WxH` from image URLs. |
144
+ | `normalize-inline-styles` | normalize | Standardizes `==mark==`, `~sub~`, and `^sup^`. |
102
145
 
103
146
  ## Contributing
104
147
 
package/dist/index.d.mts CHANGED
@@ -1,3 +1,6 @@
1
+ import { Plugin, Processor } from 'unified';
2
+ import { VFileCompatible, VFile } from 'vfile';
3
+
1
4
  // ## Interfaces
2
5
 
3
6
  /**
@@ -1141,81 +1144,88 @@ interface Properties {
1141
1144
  }
1142
1145
 
1143
1146
  /**
1144
- * Stages for mdast-plus pipeline processing.
1145
- */
1146
- type Stage = 'normalize' | 'compile' | 'finalize';
1147
+ * PipelineStage defines the execution order of plugins in the processing pipeline.
1148
+ * Plugins are sorted and executed in ascending order based on these stage values.
1149
+ */
1150
+ declare enum PipelineStage {
1151
+ /** Initial stage for parsing raw input (e.g., string to AST). */
1152
+ parse = 0,
1153
+ /** Normalization stage for cleaning up and canonicalizing the AST (e.g., GFM, Directives). */
1154
+ normalize = 100,
1155
+ /** Transformation stage for semantic changes and custom high-level logic. */
1156
+ compile = 200,
1157
+ /** Finalization stage for preparing the AST for output (e.g., Sanitize, bridge to HAST). */
1158
+ finalize = 300,
1159
+ /** Final stage for serializing the AST to the target format result. */
1160
+ stringify = 400
1161
+ }
1162
+ /** The default stage assigned to a plugin if none is specified. */
1163
+ declare const DefaultPipelineStage = PipelineStage.compile;
1164
+ /** String names corresponding to the PipelineStage levels. */
1165
+ type PipelineStageName = keyof typeof PipelineStage;
1147
1166
  /**
1148
- * Definition for an mdast plugin.
1167
+ * Configuration for a plugin within the mdast-plus pipeline.
1168
+ * It wraps a standard unified plugin with execution metadata.
1149
1169
  */
1150
1170
  interface MdastPlugin {
1151
- /** Plugin name */
1152
- name: string;
1153
- /** Processing stage the plugin belongs to */
1154
- stage?: Stage;
1155
- /** Execution order within the stage (lower numbers run first) */
1171
+ /**
1172
+ * Optional name for the plugin.
1173
+ * Used for identification in overrides and logging.
1174
+ * If not provided, defaults to the plugin function's name.
1175
+ */
1176
+ name?: string;
1177
+ /** The standard unified plugin (attacher) function. */
1178
+ plugin: Plugin<any[], any, any>;
1179
+ /**
1180
+ * Arguments passed to the plugin.
1181
+ * MUST be an array of arguments (e.g., [optionsObject]).
1182
+ */
1183
+ options?: any[];
1184
+ /** The stage in which this plugin should run. */
1185
+ stage?: PipelineStage | PipelineStageName;
1186
+ /** Execution priority within the same stage. Lower values run earlier. */
1156
1187
  order?: number;
1157
- /** Transformation function */
1158
- transform: (tree: Root, ctx: any) => Promise<void> | void;
1159
1188
  }
1160
1189
  /**
1161
- * Definition for an mdast format (parser/stringifier).
1162
- */
1163
- interface MdastFormatDefinition {
1164
- /** Function to register parser plugins */
1165
- parse?: (processor: any) => void;
1166
- /** Function to register stringifier plugins */
1167
- stringify?: (processor: any) => void;
1190
+ * Defines a document format, encompassing its input (parsing) and output (serialization) strategies.
1191
+ */
1192
+ interface MdastFormat {
1193
+ /** Unique identifier for the format (e.g., 'markdown', 'html'). */
1194
+ id: string;
1195
+ /** Human-readable title. */
1196
+ title?: string;
1197
+ /** File extensions associated with this format. */
1198
+ extensions?: string[];
1199
+ /** MIME types associated with this format. */
1200
+ mediaTypes?: string[];
1201
+ /** Plugins used for reading this format into a standard AST (Parser + Normalizer). */
1202
+ input?: MdastPlugin[];
1203
+ /** Plugins used for serializing the AST into this format (Finalizer + Stringifier). */
1204
+ output?: MdastPlugin[];
1168
1205
  }
1169
1206
  /**
1170
- * Represents an asset (e.g., image) extracted during processing.
1171
- */
1172
- interface MdastAsset {
1173
- /** Relative path or identifier for the asset */
1174
- path: string;
1175
- /** MIME type of the asset */
1176
- contentType: string;
1177
- /** Raw content as bytes */
1178
- bytes: Uint8Array;
1179
- }
1180
- /**
1181
- * Result of a conversion process.
1182
- * @template T - The type of the main content (default: string)
1183
- */
1184
- interface ConvertResult<T = string> {
1185
- /** The converted content */
1186
- content: T;
1187
- /** Extracted assets */
1188
- assets: MdastAsset[];
1189
- }
1190
- /**
1191
- * Original metadata for a node.
1207
+ * Metadata capturing the origin of a node during conversion.
1192
1208
  */
1193
1209
  interface MdastDataOrigin {
1194
- /** Source format */
1210
+ /** The original source format. */
1195
1211
  format: 'docx' | 'notion' | 'html' | 'markdown' | 'latex' | string;
1196
- /** Raw data from the source */
1212
+ /** The raw content from the source before conversion. */
1197
1213
  raw?: unknown;
1198
- /** Hash of the source content */
1214
+ /** Hash used for caching or change detection. */
1199
1215
  hash?: string;
1200
1216
  [k: string]: unknown;
1201
1217
  }
1202
- /**
1203
- * mdast node for highlighted text (mark).
1204
- */
1218
+ /** Represents a highlighted text (mark) node in mdast. */
1205
1219
  interface MdastMark extends Parent$1 {
1206
1220
  type: 'mark';
1207
1221
  children: PhrasingContent[];
1208
1222
  }
1209
- /**
1210
- * mdast node for subscript text.
1211
- */
1223
+ /** Represents a subscript text node in mdast. */
1212
1224
  interface MdastSub extends Parent$1 {
1213
1225
  type: 'sub';
1214
1226
  children: PhrasingContent[];
1215
1227
  }
1216
- /**
1217
- * mdast node for superscript text.
1218
- */
1228
+ /** Represents a superscript text node in mdast. */
1219
1229
  interface MdastSup extends Parent$1 {
1220
1230
  type: 'sup';
1221
1231
  children: PhrasingContent[];
@@ -1249,115 +1259,172 @@ declare module 'mdast' {
1249
1259
  sup: MdastSup;
1250
1260
  }
1251
1261
  }
1262
+
1252
1263
  /**
1253
- * Interface for reading input into an mdast tree.
1254
- * @template I - Input type
1264
+ * Base implementation of the fluent mdast processing pipeline.
1265
+ * Manages the plugin registry and the execution queue.
1255
1266
  */
1256
- interface MdastReader<I> {
1267
+ declare class MdastBasePipeline {
1268
+ private static readonly registry;
1257
1269
  /**
1258
- * Reads input and returns an mdast Root node.
1259
- * @param input - The input to read
1270
+ * Registers a global document format.
1271
+ * @param format - The format definition to register.
1260
1272
  */
1261
- read(input: I): Promise<Root>;
1262
- }
1263
- /**
1264
- * Interface for transforming an mdast tree.
1265
- */
1266
- interface MdastTransformer {
1273
+ static register(format: MdastFormat): void;
1267
1274
  /**
1268
- * Transforms the given mdast tree.
1269
- * @param tree - The Root node to transform
1275
+ * Retrieves a registered format by its ID.
1276
+ * @param id - The format identifier.
1277
+ * @returns The format definition or undefined if not found.
1270
1278
  */
1271
- transform(tree: Root): Promise<{
1272
- tree: Root;
1273
- assets?: MdastAsset[];
1274
- }>;
1275
- }
1276
- /**
1277
- * Interface for writing an mdast tree to an output format.
1278
- * @template Output - Output type (default: string)
1279
- */
1280
- interface MdastWriter<Output = string> {
1279
+ static getFormat(id: string): MdastFormat | undefined;
1280
+ protected input: VFileCompatible;
1281
+ protected queue: MdastPlugin[];
1281
1282
  /**
1282
- * Writes the mdast tree to the target output.
1283
- * @param tree - The Root node to write
1284
- * @param assets - Optional assets to include
1283
+ * Initializes a new pipeline instance with the given input.
1284
+ * @param input - Content to process (string, Buffer, VFile, or AST Node).
1285
1285
  */
1286
- write(tree: Root, assets?: MdastAsset[]): Promise<ConvertResult<Output>>;
1287
- }
1288
-
1289
- /**
1290
- * Fluent processor for mdast transformations.
1291
- * Allows chaining configuration and finally converting to a target format.
1292
- */
1293
- declare class FluentProcessor {
1294
- /** Map of registered format definitions */
1295
- static formats: Record<string, MdastFormatDefinition>;
1286
+ constructor(input: VFileCompatible);
1287
+ /**
1288
+ * Instance-level access to the global format registry.
1289
+ */
1290
+ getFormat(id: string): MdastFormat | undefined;
1291
+ /**
1292
+ * Resolves a format identifier or object to a valid MdastFormat.
1293
+ * @private
1294
+ */
1295
+ private resolveFormat;
1296
+ /**
1297
+ * Normalizes a plugin entry for runtime execution.
1298
+ * @protected
1299
+ */
1300
+ protected toRuntimeEntry(entry: MdastPlugin, defaultStage: PipelineStage, overrides?: Record<string, any>): MdastPlugin & {
1301
+ stage: PipelineStage;
1302
+ };
1296
1303
  /**
1297
- * Registers a new format definition.
1298
- * @param name - The name of the format (e.g., 'docx')
1299
- * @param definition - The format definition containing parse/stringify logic
1304
+ * Ensures that input plugins (parser, normalizers) are present in the queue.
1305
+ * Adds implicit plugins if no parser is detected.
1306
+ * @protected
1300
1307
  */
1301
- static registerFormat(name: string, definition: MdastFormatDefinition): void;
1302
- private processor;
1303
- private input;
1304
- private inputFormat;
1305
- private plugins;
1306
- private globalData;
1308
+ protected ensureInputPlugins(queue: MdastPlugin[], overrides?: Record<string, any>, maxStage?: PipelineStage): void;
1307
1309
  /**
1308
- * Creates a new FluentProcessor instance.
1309
- * @param input - The input content (string or mdast tree)
1310
+ * Configures the input format and adds its associated plugins to the pipeline.
1311
+ * @param fmt - Format ID or definition.
1312
+ * @param overrides - Optional map to override plugin options by plugin name.
1313
+ * @returns The pipeline instance for chaining.
1310
1314
  */
1311
- constructor(input: any);
1315
+ from(fmt: string | MdastFormat, overrides?: Record<string, any>): this;
1312
1316
  /**
1313
- * Specifies the input format.
1314
- * @param format - The input format name (default: 'markdown')
1317
+ * Processes the pipeline and serializes the result into the specified format.
1318
+ * @param fmt - Target format ID or definition.
1319
+ * @param overrides - Optional map to override plugin options.
1320
+ * @returns A promise resolving to a VFile containing the result.
1315
1321
  */
1316
- from(format: string): this;
1322
+ to(fmt: string | MdastFormat, overrides?: Record<string, any>): Promise<VFile>;
1317
1323
  /**
1318
- * Adds a plugin to the processing pipeline.
1319
- * @param plugin - The mdast plugin to use
1324
+ * Adds a plugin to the pipeline's compile stage.
1325
+ * @param plugin - The unified plugin function.
1326
+ * @param options - Arguments for the plugin.
1327
+ * @returns The pipeline instance for chaining.
1320
1328
  */
1321
- use(plugin: MdastPlugin): this;
1329
+ use(plugin: any, ...options: any[]): this;
1322
1330
  /**
1323
- * Merges global data into the processor.
1324
- * @param data - Key-value pairs to store in global data
1331
+ * Adds a plugin to the pipeline at a specific stage.
1332
+ * @param stage - The stage name or numeric value.
1333
+ * @param plugin - The unified plugin function.
1334
+ * @param options - Arguments for the plugin.
1335
+ * @returns The pipeline instance for chaining.
1325
1336
  */
1326
- data(data: Record<string, any>): this;
1337
+ useAt(stage: PipelineStageName, plugin: any, ...options: any[]): this;
1327
1338
  /**
1328
- * Converts the input content to the specified format.
1329
- * @param format - The output format name
1330
- * @returns A promise resolving to the conversion result (content and assets)
1339
+ * Sets the priority order for the most recently added plugin.
1340
+ * Plugins with lower order run earlier within the same stage.
1341
+ * @param order - Numeric priority.
1342
+ * @returns The pipeline instance for chaining.
1331
1343
  */
1332
- to(format: string): Promise<ConvertResult>;
1344
+ priority(order: number): this;
1333
1345
  /**
1334
- * Helper to convert content to Markdown.
1335
- * @returns A promise resolving to the Markdown string
1346
+ * Assembles a unified processor based on the sorted plugin queue.
1347
+ * @protected
1348
+ */
1349
+ protected assembleProcessor(queue: MdastPlugin[]): Processor;
1350
+ }
1351
+ /**
1352
+ * Extended pipeline with convenience methods for common formats.
1353
+ */
1354
+ declare class MdastPipeline extends MdastBasePipeline {
1355
+ /**
1356
+ * Finalizes the pipeline and returns the result as a Markdown string.
1336
1357
  */
1337
1358
  toMarkdown(): Promise<string>;
1338
1359
  /**
1339
- * Helper to convert content to HTML.
1340
- * @returns A promise resolving to the HTML string
1360
+ * Finalizes the pipeline and returns a VFile containing the Markdown result.
1361
+ */
1362
+ toMarkdownVFile(): Promise<VFile>;
1363
+ /**
1364
+ * Finalizes the pipeline and returns the result as an HTML string.
1365
+ */
1366
+ toHtml(): Promise<string>;
1367
+ /**
1368
+ * Finalizes the pipeline and returns a VFile containing the HTML result.
1341
1369
  */
1370
+ toHtmlVFile(): Promise<VFile>;
1371
+ /**
1372
+ * Finalizes the pipeline and returns the resulting AST (Root node).
1373
+ * @param options - Configuration for the extraction.
1374
+ * @param options.stage - Run the pipeline up to this stage only.
1375
+ * @param options.overrides - Map for plugin option overrides.
1376
+ */
1377
+ toAst(options?: {
1378
+ stage?: PipelineStageName;
1379
+ overrides?: Record<string, any>;
1380
+ }): Promise<Root>;
1381
+ /** Alias for toHtml() */
1342
1382
  toHTML(): Promise<string>;
1383
+ /** Alias for toAst() */
1384
+ toAST(options?: {
1385
+ stage?: PipelineStageName;
1386
+ overrides?: Record<string, any>;
1387
+ }): Promise<Root>;
1343
1388
  }
1344
1389
  /**
1345
1390
  * Entry point for the fluent mdast-plus API.
1346
1391
  * @param input - The input content (string or mdast tree)
1347
1392
  * @returns A FluentProcessor instance
1348
1393
  */
1349
- declare function mdast(input: any): FluentProcessor;
1394
+ declare function mdast(input: VFileCompatible): MdastPipeline;
1395
+
1396
+ /**
1397
+ * Markdown format definition.
1398
+ *
1399
+ * Supports GFM, Directives, Math, and Frontmatter.
1400
+ * Provides a bidirectional mapping between Markdown strings and mdast-plus ASTs.
1401
+ */
1402
+ declare const markdownFormat: MdastFormat;
1350
1403
 
1351
1404
  /**
1352
- * Unified plugin/configuration for Markdown format.
1353
- * Includes GFM, directives, math, and frontmatter.
1405
+ * HTML format definition.
1406
+ *
1407
+ * Provides a bidirectional mapping between HTML strings and mdast-plus ASTs.
1408
+ * Includes built-in sanitization and support for table spans and image dimensions.
1354
1409
  */
1355
- declare function markdownFormat(this: any): void;
1410
+ declare const htmlFormat: MdastFormat;
1356
1411
 
1357
1412
  /**
1358
- * Unified plugin/configuration for HTML format.
1359
- * Includes mdast-to-hast conversion, sanitization (with table span support), and stringification.
1413
+ * Pass-through compiler that returns the AST as-is.
1414
+ * Essential for unified processes that should output an object (the AST)
1415
+ * instead of a serialized string.
1416
+ */
1417
+ declare function astCompiler(this: any): void;
1418
+ /**
1419
+ * Parser for stringified JSON AST input.
1420
+ * Allows the pipeline to accept a JSON string and treat it as a unist tree.
1421
+ */
1422
+ declare function jsonParser(this: any): void;
1423
+ /**
1424
+ * AST (MDAST) format definition.
1425
+ * Supports reading from JSON strings and provides full normalization
1426
+ * through the standard mdast-plus plugin set.
1360
1427
  */
1361
- declare function htmlFormat(this: any): void;
1428
+ declare const astFormat: MdastFormat;
1362
1429
 
1363
- export { type ConvertResult, FluentProcessor, type MdastAsset, type MdastDataOrigin, type MdastFormatDefinition, type MdastMark, type MdastPlugin, type MdastReader, type MdastSub, type MdastSup, type MdastTransformer, type MdastWriter, type Stage, htmlFormat, markdownFormat, mdast };
1430
+ export { DefaultPipelineStage, MdastBasePipeline, type MdastDataOrigin, type MdastFormat, type MdastMark, MdastPipeline, type MdastPlugin, type MdastSub, type MdastSup, PipelineStage, type PipelineStageName, astCompiler, astFormat, htmlFormat, jsonParser, markdownFormat, mdast };