@isdk/mdast-plus 0.1.1

package/README.cn.md

@@ -0,0 +1,109 @@
+# @isdk/mdast-plus
+
+> 基于 unified, remark 和 rehype 的“语义优先” Markdown 处理工具包。
+
+[English](./README.md) | 简体中文 | [GitHub](https://github.com/isdk/mdast-plus.js)
+
+[![NPM version](https://img.shields.io/npm/v/@isdk/mdast-plus.svg)](https://www.npmjs.com/package/@isdk/mdast-plus)
+
+`@isdk/mdast-plus` 是 unified 生态系统的强大扩展，旨在为 Markdown 内容提供一致且语义优先的规范化与转换。它通过 Fluent API 和分阶段的插件系统简化了复杂的处理工作流。
+
+## 特性
+
+- **Fluent API**: 链式调用接口 `mdast(input).use(plugin).toHTML()`。
+- **分阶段插件**: 将转换组织为 `normalize`、`compile` 和 `finalize` 阶段，支持优先级排序。
+- **语义化规范**:
+  - **指令 (Directives)**: 规范化提示框 (Admonition) 名称并从标签中提取标题。
+  - **表格跨行/跨列**: 支持 HTML 输出中的 `rowspan` 和 `colspan`。
+  - **代码元数据**: 对代码块元数据字符串进行结构化解析。
+  - **图片尺寸**: 支持 URL 糖语法 (例如 `image.png#=500x300`) 来设置图片尺寸。
+- **深度类型支持**: 基于 TypeScript 构建，完整支持 unist/mdast 的模块扩充。
+
+## 安装
+
+```bash
+npm install @isdk/mdast-plus
+# 或
+pnpm add @isdk/mdast-plus
+```
+
+## 基本用法
+
+### HTML 转换
+
+```typescript
+import { mdast } from '@isdk/mdast-plus';
+
+const html = await mdast(':::warning[重要提示]\n请小心！\n:::')
+  .toHTML();
+// 结果: <div title="重要提示" class="warning"><p>请小心！</p></div>
+```
+
+### 图片尺寸
+
+```typescript
+const html = await mdast('![Cat](cat.png#=500x300)').toHTML();
+// 结果: <img src="cat.png" alt="Cat" width="500" height="300">
+```
+
+### 高级工作流
+
+```typescript
+const { content, assets } = await mdast(myInput)
+  .data({ myGlobal: 'value' })
+  .use({
+    name: 'my-plugin',
+    stage: 'compile',
+    transform: async (tree) => {
+      // 转换 AST
+    }
+  })
+  .to('html');
+```
+
+### 任意格式支持
+
+您可以注册自定义的输入或输出格式：
+
+```typescript
+import { FluentProcessor, mdast } from '@isdk/mdast-plus';
+
+// 注册自定义输出格式
+FluentProcessor.registerFormat('reverse', {
+  stringify: (p) => {
+    p.Compiler = (tree) => {
+      // 您的自定义序列化逻辑
+      return '...';
+    };
+  }
+});
+
+const result = await mdast('Hello').to('reverse');
+```
+
+> **注意**: 格式名称不区分大小写（内部始终转换为小写）。
+
+## 分阶段处理
+
+插件根据它们的 `stage` (阶段) 和 `order` (顺序) 执行：
+
+1.  **normalize** (order 0-100): 清理并规范化树。
+2.  **compile** (order 0-100): 高级语义转换。
+3.  **finalize** (order 0-100): 输出前的最后准备。
+
+## 内置核心插件
+
+| 插件 | 阶段 | 描述 |
+| :--- | :--- | :--- |
+| `normalize-directive` | normalize | 处理别名 (`warn` -> `warning`) 并提取标题。 |
+| `normalize-table-span` | normalize | 将表格单元格跨度迁移到 `hProperties`。 |
+| `extract-code-meta` | normalize | 从代码块元数据中解析 `title="foo"`。 |
+| `image-size` | normalize | 从图片 URL 中解析 `#=WxH`。 |
+
+## 贡献
+
+请查看 [CONTRIBUTING.cn.md](./CONTRIBUTING.cn.md) 以获取有关如何贡献本项目的指南。
+
+## 许可证
+
+[MIT](./LICENSE-MIT)

package/README.md

@@ -0,0 +1,109 @@
+# @isdk/mdast-plus
+
+> A "Semantic-First" Markdown processing toolkit based on unified, remark and rehype.
+
+English | [简体中文](./README.cn.md) | [GitHub](https://github.com/isdk/mdast-plus.js)
+
+[![NPM version](https://img.shields.io/npm/v/@isdk/mdast-plus.svg)](https://www.npmjs.com/package/@isdk/mdast-plus)
+
+`@isdk/mdast-plus` is a powerful extension to the unified ecosystem, designed to provide consistent, semantic-first normalization and transformation of Markdown content. It simplifies complex processing pipelines with a fluent API and a staged plugin system.
+
+## Features
+
+- **Fluent API**: Chainable interface `mdast(input).use(plugin).toHTML()`.
+- **Staged Plugins**: Organize transformations into `normalize`, `compile`, and `finalize` stages with priority ordering.
+- **Semantic Normalization**:
+  - **Directives**: Canonicalizes admonition names and extracts titles from labels.
+  - **Table Spans**: Support for `rowspan` and `colspan` in HTML output.
+  - **Code Meta**: Structured parsing of code block metadata strings.
+  - **Image Sizing**: URL "sugar" support (e.g., `image.png#=500x300`) for image dimensions.
+- **Deeply Typed**: Built on TypeScript with full support for unist/mdast module augmentation.
+
+## Installation
+
+```bash
+npm install @isdk/mdast-plus
+# or
+pnpm add @isdk/mdast-plus
+```
+
+## Basic Usage
+
+### HTML Conversion
+
+```typescript
+import { mdast } from '@isdk/mdast-plus';
+
+const html = await mdast(':::warning[Special Note]\nBe careful!\n:::')
+  .toHTML();
+// Result: <div title="Special Note" class="warning"><p>Be careful!</p></div>
+```
+
+### Image Sizing
+
+```typescript
+const html = await mdast('![Cat](cat.png#=500x300)').toHTML();
+// Result: <img src="cat.png" alt="Cat" width="500" height="300">
+```
+
+### Advanced Pipeline
+
+```typescript
+const { content, assets } = await mdast(myInput)
+  .data({ myGlobal: 'value' })
+  .use({
+    name: 'my-plugin',
+    stage: 'compile',
+    transform: async (tree) => {
+      // transform the AST
+    }
+  })
+  .to('html');
+```
+
+### Arbitrary Formats
+
+You can register custom input or output formats:
+
+```typescript
+import { FluentProcessor, mdast } from '@isdk/mdast-plus';
+
+// Register a custom output format
+FluentProcessor.registerFormat('reverse', {
+  stringify: (p) => {
+    p.Compiler = (tree) => {
+      // your custom stringification logic
+      return '...';
+    };
+  }
+});
+
+const result = await mdast('Hello').to('reverse');
+```
+
+> **Note**: Format names are case-insensitive (always converted to lowercase internally).
+
+## Staged Processing
+
+Plugins are executed based on their `stage` and `order`:
+
+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.
+
+## Core Plugins Included
+
+| Plugin | Stage | Description |
+| :--- | :--- | :--- |
+| `normalize-directive` | normalize | Handles aliases (`warn` -> `warning`) and extracts titles. |
+| `normalize-table-span` | normalize | Migrates table cell spans to `hProperties`. |
+| `extract-code-meta` | normalize | Parses `title="foo"` from code block meta. |
+| `image-size` | normalize | Parses `#=WxH` from image URLs. |
+
+## Contributing
+
+Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute to this project.
+
+## License
+
+[MIT](./LICENSE-MIT)