@isdk/mdast-plus 0.1.1

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var e,t=Object.create,r=Object.defineProperty,i=Object.getOwnPropertyDescriptor,n=Object.getOwnPropertyNames,a=Object.getPrototypeOf,s=Object.prototype.hasOwnProperty,o=(e,t,a,o)=>{if(t&&"object"==typeof t||"function"==typeof t)for(let u of n(t))s.call(e,u)||u===a||r(e,u,{get:()=>t[u],enumerable:!(o=i(t,u))||o.enumerable});return e},u=(e,i,n)=>(n=null!=e?t(a(e)):{},o(!i&&e&&e.__esModule?n:r(n,"default",{value:e,enumerable:!0}),e)),l={};((e,t)=>{for(var i in t)r(e,i,{get:t[i],enumerable:!0})})(l,{FluentProcessor:()=>B,htmlFormat:()=>z,markdownFormat:()=>w,mdast:()=>C}),module.exports=(e=l,o(r({},"__esModule",{value:!0}),e));var c=require("unified"),m=u(require("remark-parse")),h=u(require("remark-stringify")),f=u(require("rehype-parse")),d=u(require("rehype-remark")),p=u(require("remark-gfm")),v=u(require("remark-directive")),g=u(require("remark-math")),y=u(require("remark-frontmatter"));function w(){const e=this.data();var t,r;r={handlers:{mark:(e,t,r)=>"=="+r.containerPhrasing(e,{before:"==",after:"=="})+"==",sub:(e,t,r)=>"~"+r.containerPhrasing(e,{before:"~",after:"~"})+"~",sup:(e,t,r)=>"^"+r.containerPhrasing(e,{before:"^",after:"^"})+"^"}},e[t="toMarkdownExtensions"]?e[t].push(r):e[t]=[r],this.use(p.default,{singleTilde:!1}).use(v.default).use(g.default).use(y.default,["yaml","toml"])}var b=u(require("remark-rehype")),k=u(require("rehype-sanitize")),q=u(require("rehype-stringify"));function z(){this.use(b.default).use(k.default,{...k.defaultSchema,tagNames:[...k.defaultSchema.tagNames||[],"mark","sub","sup"],attributes:{...k.defaultSchema.attributes,"*":[...k.defaultSchema.attributes?.["*"]||[],"className","id","style"],td:[...k.defaultSchema.attributes?.td||[],"rowSpan","colSpan","rowspan","colspan"],th:[...k.defaultSchema.attributes?.th||[],"rowSpan","colSpan","rowspan","colspan"],img:[...k.defaultSchema.attributes?.img||[],"width","height"]}}).use(q.default)}var x=require("unist-util-visit"),j={error:"danger",warn:"warning",success:"tip",important:"important",caution:"caution",note:"note"},O={name:"normalize-directive",stage:"normalize",order:10,transform:async e=>{(0,x.visit)(e,["containerDirective","leafDirective","textDirective"],e=>{const t=e,r=t.name.toLowerCase();if(t.name=j[r]||r,t.children&&t.children.length>0){const e=t.children[0];if(e.data?.directiveLabel||"directiveLabel"===e.type){const r=e;let i="";(0,x.visit)(r,"text",e=>{i+=e.value}),i&&!t.attributes?.title&&(t.attributes=t.attributes||{},t.attributes.title=i.trim()),t.children.shift()}}t.attributes?.title&&(t.attributes.title=String(t.attributes.title).trim()),t.data=t.data||{},t.data.hName=t.data.hName||("containerDirective"===t.type?"div":"span"),t.data.hProperties={...t.data.hProperties||{},...t.attributes,className:[t.name,t.data.hProperties?.className].filter(Boolean).join(" ")}})}},S=require("unist-util-visit"),D={name:"normalize-table-span",stage:"normalize",order:20,transform:async e=>{(0,S.visit)(e,"tableCell",e=>{if(e.data){const{rowspan:t,colspan:r}=e.data;e.data.hProperties=e.data.hProperties||{},void 0!==t&&(e.data.hProperties.rowSpan=t,delete e.data.rowspan),void 0!==r&&(e.data.hProperties.colSpan=r,delete e.data.colspan)}})}},F=require("unist-util-visit");var M={name:"extract-code-meta",stage:"normalize",order:30,transform:async e=>{(0,F.visit)(e,"code",e=>{if(e.meta){const t=function(e){const t={},r=/([a-zA-Z0-9_-]+)(?:=?(?:"([^"]*)"|'([^']*)'|([^ \t\n\r\f]+)))?/g;let i;for(;null!==(i=r.exec(e));){const e=i[1],r=i[2]||i[3]||i[4]||"";t[e]=r}return t}(e.meta),r=e.data=e.data||{};t.title&&(r.title=t.title),t.filename&&(r.filename=t.filename),r.kv={...r.kv||{},...t}}})}},N=require("unist-util-visit"),_={name:"image-size",stage:"normalize",order:40,transform:async e=>{(0,N.visit)(e,"image",e=>{const t=e.data=e.data||{},r=t.hProperties=t.hProperties||{},i=/[#?&](?:width=([0-9]+))?(?:&?height=([0-9]+))?(?:=([0-9]+)x([0-9]+))?$/,n=e.url.match(i);if(n){const t=n[1]||n[3],a=n[2]||n[4];t&&!r.width&&(r.width=parseInt(t,10)),a&&!r.height&&(r.height=parseInt(a,10)),e.url=e.url.replace(i,"")}t.width&&!r.width&&(r.width=t.width),t.height&&!r.height&&(r.height=t.height)})}},I=require("unist-util-visit");function L(e,t){return{type:e,children:t,data:{hName:e}}}var T={name:"normalize-inline-styles",stage:"normalize",transform:e=>{!function(e){(0,I.visit)(e,"text",(e,t,r)=>{if(!r||void 0===t)return;let i=e.value,n=0;const a=[];let s=!1;const o=/(==[^=]+==|~[^~]+~|\^[^^]+\^)/g;let u;for(;null!==(u=o.exec(i));){s=!0;const e=u[0],t=u.index;t>n&&a.push({type:"text",value:i.slice(n,t)});let r="mark",l="";e.startsWith("==")?(r="mark",l=e.slice(2,-2)):e.startsWith("~")?(r="sub",l=e.slice(1,-1)):e.startsWith("^")&&(r="sup",l=e.slice(1,-1)),a.push(L(r,[{type:"text",value:l}])),n=o.lastIndex}return s?(n<i.length&&a.push({type:"text",value:i.slice(n)}),r.children.splice(t,1,...a),t+a.length):void 0})}(e)}},A=class e{constructor(e){this.inputFormat="markdown",this.plugins=[],this.globalData={},this.input=e,this.processor=(0,c.unified)(),this.use(O),this.use(D),this.use(M),this.use(_),this.use(T)}static registerFormat(t,r){e.formats[t.toLowerCase()]=r}from(e){return this.inputFormat=e.toLowerCase(),this}use(e){return this.plugins.push(e),this}data(e){return this.globalData={...this.globalData,...e},this}async to(t){t=t.toLowerCase();const r=e.formats[this.inputFormat];r?.parse&&r.parse(this.processor);let i="string"==typeof this.input?this.processor.parse(this.input):this.input;i.data={...i.data,...this.globalData};const n=[...this.plugins].sort((e,t)=>{const r={normalize:0,compile:1,finalize:2},i=e.stage||"normalize",n=t.stage||"normalize";return i!==n?r[i]-r[n]:(e.order||0)-(t.order||0)});for(const e of n)await e.transform(i,this.processor);const a=(0,c.unified)().data("settings",this.processor.data("settings")),s=e.formats[t];s?.stringify&&s.stringify(a),"markdown"!==t||s||a.use(h.default).use(w);const o=await a.run(i),u=a.stringify(o),l=[];return i.data&&i.data.assets&&l.push(...i.data.assets),{content:u,assets:l}}async toMarkdown(){return(await this.to("markdown")).content}async toHTML(){return(await this.to("html")).content}};A.formats={markdown:{parse:e=>e.use(m.default).use(w),stringify:e=>e.use(h.default).use(w)},html:{parse:e=>e.use(f.default).use(d.default),stringify:e=>e.use(z)},ast:{parse:e=>{}}};var B=A;function C(e){return new B(e)}

package/dist/index.mjs

@@ -0,0 +1 @@
+import{unified as t}from"unified";import r from"remark-parse";import i from"remark-stringify";import e from"rehype-parse";import s from"rehype-remark";import a from"remark-gfm";import n from"remark-directive";import o from"remark-math";import m from"remark-frontmatter";function c(){const t=this.data();var r,i;i={handlers:{mark:(t,r,i)=>"=="+i.containerPhrasing(t,{before:"==",after:"=="})+"==",sub:(t,r,i)=>"~"+i.containerPhrasing(t,{before:"~",after:"~"})+"~",sup:(t,r,i)=>"^"+i.containerPhrasing(t,{before:"^",after:"^"})+"^"}},t[r="toMarkdownExtensions"]?t[r].push(i):t[r]=[i],this.use(a,{singleTilde:!1}).use(n).use(o).use(m,["yaml","toml"])}import l from"remark-rehype";import f,{defaultSchema as p}from"rehype-sanitize";import h from"rehype-stringify";function u(){this.use(l).use(f,{...p,tagNames:[...p.tagNames||[],"mark","sub","sup"],attributes:{...p.attributes,"*":[...p.attributes?.["*"]||[],"className","id","style"],td:[...p.attributes?.td||[],"rowSpan","colSpan","rowspan","colspan"],th:[...p.attributes?.th||[],"rowSpan","colSpan","rowspan","colspan"],img:[...p.attributes?.img||[],"width","height"]}}).use(h)}import{visit as d}from"unist-util-visit";var v={error:"danger",warn:"warning",success:"tip",important:"important",caution:"caution",note:"note"},g={name:"normalize-directive",stage:"normalize",order:10,transform:async t=>{d(t,["containerDirective","leafDirective","textDirective"],t=>{const r=t,i=r.name.toLowerCase();if(r.name=v[i]||i,r.children&&r.children.length>0){const t=r.children[0];if(t.data?.directiveLabel||"directiveLabel"===t.type){let i="";d(t,"text",t=>{i+=t.value}),i&&!r.attributes?.title&&(r.attributes=r.attributes||{},r.attributes.title=i.trim()),r.children.shift()}}r.attributes?.title&&(r.attributes.title=String(r.attributes.title).trim()),r.data=r.data||{},r.data.hName=r.data.hName||("containerDirective"===r.type?"div":"span"),r.data.hProperties={...r.data.hProperties||{},...r.attributes,className:[r.name,r.data.hProperties?.className].filter(Boolean).join(" ")}})}};import{visit as y}from"unist-util-visit";var w={name:"normalize-table-span",stage:"normalize",order:20,transform:async t=>{y(t,"tableCell",t=>{if(t.data){const{rowspan:r,colspan:i}=t.data;t.data.hProperties=t.data.hProperties||{},void 0!==r&&(t.data.hProperties.rowSpan=r,delete t.data.rowspan),void 0!==i&&(t.data.hProperties.colSpan=i,delete t.data.colspan)}})}};import{visit as k}from"unist-util-visit";var z={name:"extract-code-meta",stage:"normalize",order:30,transform:async t=>{k(t,"code",t=>{if(t.meta){const r=function(t){const r={},i=/([a-zA-Z0-9_-]+)(?:=?(?:"([^"]*)"|'([^']*)'|([^ \t\n\r\f]+)))?/g;let e;for(;null!==(e=i.exec(t));){const t=e[1],i=e[2]||e[3]||e[4]||"";r[t]=i}return r}(t.meta),i=t.data=t.data||{};r.title&&(i.title=r.title),r.filename&&(i.filename=r.filename),i.kv={...i.kv||{},...r}}})}};import{visit as b}from"unist-util-visit";var x={name:"image-size",stage:"normalize",order:40,transform:async t=>{b(t,"image",t=>{const r=t.data=t.data||{},i=r.hProperties=r.hProperties||{},e=/[#?&](?:width=([0-9]+))?(?:&?height=([0-9]+))?(?:=([0-9]+)x([0-9]+))?$/,s=t.url.match(e);if(s){const r=s[1]||s[3],a=s[2]||s[4];r&&!i.width&&(i.width=parseInt(r,10)),a&&!i.height&&(i.height=parseInt(a,10)),t.url=t.url.replace(e,"")}r.width&&!i.width&&(i.width=r.width),r.height&&!i.height&&(i.height=r.height)})}};import{visit as S}from"unist-util-visit";function D(t,r){return{type:t,children:r,data:{hName:t}}}var N={name:"normalize-inline-styles",stage:"normalize",transform:t=>{!function(t){S(t,"text",(t,r,i)=>{if(!i||void 0===r)return;let e=t.value,s=0;const a=[];let n=!1;const o=/(==[^=]+==|~[^~]+~|\^[^^]+\^)/g;let m;for(;null!==(m=o.exec(e));){n=!0;const t=m[0],r=m.index;r>s&&a.push({type:"text",value:e.slice(s,r)});let i="mark",c="";t.startsWith("==")?(i="mark",c=t.slice(2,-2)):t.startsWith("~")?(i="sub",c=t.slice(1,-1)):t.startsWith("^")&&(i="sup",c=t.slice(1,-1)),a.push(D(i,[{type:"text",value:c}])),s=o.lastIndex}return n?(s<e.length&&a.push({type:"text",value:e.slice(s)}),i.children.splice(r,1,...a),r+a.length):void 0})}(t)}},M=class r{constructor(r){this.inputFormat="markdown",this.plugins=[],this.globalData={},this.input=r,this.processor=t(),this.use(g),this.use(w),this.use(z),this.use(x),this.use(N)}static registerFormat(t,i){r.formats[t.toLowerCase()]=i}from(t){return this.inputFormat=t.toLowerCase(),this}use(t){return this.plugins.push(t),this}data(t){return this.globalData={...this.globalData,...t},this}async to(e){e=e.toLowerCase();const s=r.formats[this.inputFormat];s?.parse&&s.parse(this.processor);let a="string"==typeof this.input?this.processor.parse(this.input):this.input;a.data={...a.data,...this.globalData};const n=[...this.plugins].sort((t,r)=>{const i={normalize:0,compile:1,finalize:2},e=t.stage||"normalize",s=r.stage||"normalize";return e!==s?i[e]-i[s]:(t.order||0)-(r.order||0)});for(const t of n)await t.transform(a,this.processor);const o=t().data("settings",this.processor.data("settings")),m=r.formats[e];m?.stringify&&m.stringify(o),"markdown"!==e||m||o.use(i).use(c);const l=await o.run(a),f=o.stringify(l),p=[];return a.data&&a.data.assets&&p.push(...a.data.assets),{content:f,assets:p}}async toMarkdown(){return(await this.to("markdown")).content}async toHTML(){return(await this.to("html")).content}};M.formats={markdown:{parse:t=>t.use(r).use(c),stringify:t=>t.use(i).use(c)},html:{parse:t=>t.use(e).use(s),stringify:t=>t.use(u)},ast:{parse:t=>{}}};var I=M;function L(t){return new I(t)}export{I as FluentProcessor,u as htmlFormat,c as markdownFormat,L as mdast};

package/docs/README.md

@@ -0,0 +1,113 @@
+**@isdk/mdast-plus**
+
+***
+
+# @isdk/mdast-plus
+
+> A "Semantic-First" Markdown processing toolkit based on unified, remark and rehype.
+
+English | [简体中文](_media/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](_media/CONTRIBUTING.md) for guidelines on how to contribute to this project.
+
+## License
+
+[MIT](_media/LICENSE-MIT)

package/docs/_media/CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contributing to @isdk/mdast-plus
+
+Thank you for your interest in contributing to `@isdk/mdast-plus`! This document provides guidelines for contributing to the project.
+
+## Architecture Overview
+
+`@isdk/mdast-plus` is built on the `unified` ecosystem. It extends `mdast` (Markdown Abstract Syntax Tree) with semantic-first principles.
+
+### 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:
+    *   `normalize`: Cleanup and canonicalize the tree.
+    *   `compile`: High-level semantic transformations.
+    *   `finalize`: Final preparation before output.
+3.  **Universal Data Protocols**: Nodes use `node.data` for metadata, and `node.data.hProperties` for HTML attributes.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js (Latest LTS recommended)
+- [pnpm](https://pnpm.io/) (used for dependency management)
+
+### Installation
+
+```bash
+git clone https://github.com/isdk/mdast-plus.js.git
+cd mdast-plus.js
+pnpm install
+```
+
+## Development Workflow
+
+### Building
+
+```bash
+pnpm run build
+```
+
+### Testing
+
+We use `vitest` for testing. Add your tests in the `test/` directory.
+
+```bash
+pnpm run test        # Run tests once
+```
+
+### Linting
+
+```bash
+pnpm run lint
+```
+
+## Adding a New Plugin
+
+1.  Create your plugin in `src/plugins/`.
+2.  Implement the `MdastPlugin` interface:
+
+```typescript
+import { MdastPlugin } from '../types';
+
+export const myPlugin: MdastPlugin = {
+  name: 'my-plugin',
+  stage: 'normalize', // 'normalize' | '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.
+
+## Adding a New Format
+
+1. Implement the `MdastFormatDefinition` interface.
+2. Register it using `FluentProcessor.registerFormat(name, definition)`.
+
+```typescript
+import { FluentProcessor } from '../pipeline';
+
+FluentProcessor.registerFormat('json', {
+  stringify: (processor) => {
+    processor.Compiler = (tree) => JSON.stringify(tree);
+  }
+});
+```
+
+> **Note**: Format names are case-insensitive.
+
+## Coding Standards
+
+- Use **TypeScript** for all new code.
+- Follow the existing code style and formatting (use Prettier/ESLint).
+- Ensure all new features are covered by **tests**.
+- Use **semantic-first** principles: focus on the meaning of the content, not just its visual representation.
+
+## Submission Guidelines
+
+- Create a feature branch for your changes.
+- Ensure all tests pass.
+- Update documentation (`README.md`, `README.cn.md`) if necessary.
+- Submit a Pull Request with a clear description of your changes.
+
+## License
+
+By contributing to this project, you agree that your contributions will be licensed under the [MIT License](./LICENSE-MIT).

package/docs/_media/LICENSE-MIT

@@ -0,0 +1,22 @@
+Copyright (c) 2025 Riceball LEE
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/docs/_media/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/docs/classes/FluentProcessor.md

@@ -0,0 +1,194 @@
+[**@isdk/mdast-plus**](../README.md)
+
+***
+
+[@isdk/mdast-plus](../globals.md) / FluentProcessor
+
+# Class: FluentProcessor
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:24](https://github.com/isdk/mdast-plus.js/blob/c94d215035e579925cf60814f0a5c05c543ca784/src/pipeline.ts#L24)
+
+Fluent processor for mdast transformations.
+Allows chaining configuration and finally converting to a target format.
+
+## Constructors
+
+### Constructor
+
+> **new FluentProcessor**(`input`): `FluentProcessor`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:59](https://github.com/isdk/mdast-plus.js/blob/c94d215035e579925cf60814f0a5c05c543ca784/src/pipeline.ts#L59)
+
+Creates a new FluentProcessor instance.
+
+#### Parameters
+
+##### input
+
+`any`
+
+The input content (string or mdast tree)
+
+#### Returns
+
+`FluentProcessor`
+
+## Properties
+
+### formats
+
+> `static` **formats**: `Record`\<`string`, [`MdastFormatDefinition`](../interfaces/MdastFormatDefinition.md)\>
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:26](https://github.com/isdk/mdast-plus.js/blob/c94d215035e579925cf60814f0a5c05c543ca784/src/pipeline.ts#L26)
+
+Map of registered format definitions
+
+## Methods
+
+### data()
+
+> **data**(`data`): `this`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:93](https://github.com/isdk/mdast-plus.js/blob/c94d215035e579925cf60814f0a5c05c543ca784/src/pipeline.ts#L93)
+
+Merges global data into the processor.
+
+#### Parameters
+
+##### data
+
+`Record`\<`string`, `any`\>
+
+Key-value pairs to store in global data
+
+#### Returns
+
+`this`
+
+***
+
+### from()
+
+> **from**(`format`): `this`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:75](https://github.com/isdk/mdast-plus.js/blob/c94d215035e579925cf60814f0a5c05c543ca784/src/pipeline.ts#L75)
+
+Specifies the input format.
+
+#### Parameters
+
+##### format
+
+`string`
+
+The input format name (default: 'markdown')
+
+#### Returns
+
+`this`
+
+***
+
+### to()
+
+> **to**(`format`): `Promise`\<[`ConvertResult`](../interfaces/ConvertResult.md)\<`string`\>\>
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:103](https://github.com/isdk/mdast-plus.js/blob/c94d215035e579925cf60814f0a5c05c543ca784/src/pipeline.ts#L103)
+
+Converts the input content to the specified format.
+
+#### Parameters
+
+##### format
+
+`string`
+
+The output format name
+
+#### Returns
+
+`Promise`\<[`ConvertResult`](../interfaces/ConvertResult.md)\<`string`\>\>
+
+A promise resolving to the conversion result (content and assets)
+
+***
+
+### toHTML()
+
+> **toHTML**(): `Promise`\<`string`\>
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:173](https://github.com/isdk/mdast-plus.js/blob/c94d215035e579925cf60814f0a5c05c543ca784/src/pipeline.ts#L173)
+
+Helper to convert content to HTML.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+A promise resolving to the HTML string
+
+***
+
+### toMarkdown()
+
+> **toMarkdown**(): `Promise`\<`string`\>
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:164](https://github.com/isdk/mdast-plus.js/blob/c94d215035e579925cf60814f0a5c05c543ca784/src/pipeline.ts#L164)
+
+Helper to convert content to Markdown.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+A promise resolving to the Markdown string
+
+***
+
+### use()
+
+> **use**(`plugin`): `this`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:84](https://github.com/isdk/mdast-plus.js/blob/c94d215035e579925cf60814f0a5c05c543ca784/src/pipeline.ts#L84)
+
+Adds a plugin to the processing pipeline.
+
+#### Parameters
+
+##### plugin
+
+[`MdastPlugin`](../interfaces/MdastPlugin.md)
+
+The mdast plugin to use
+
+#### Returns
+
+`this`
+
+***
+
+### registerFormat()
+
+> `static` **registerFormat**(`name`, `definition`): `void`
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:45](https://github.com/isdk/mdast-plus.js/blob/c94d215035e579925cf60814f0a5c05c543ca784/src/pipeline.ts#L45)
+
+Registers a new format definition.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the format (e.g., 'docx')
+
+##### definition
+
+[`MdastFormatDefinition`](../interfaces/MdastFormatDefinition.md)
+
+The format definition containing parse/stringify logic
+
+#### Returns
+
+`void`

package/docs/functions/htmlFormat.md

@@ -0,0 +1,24 @@
+[**@isdk/mdast-plus**](../README.md)
+
+***
+
+[@isdk/mdast-plus](../globals.md) / htmlFormat
+
+# Function: htmlFormat()
+
+> **htmlFormat**(`this`): `void`
+
+Defined in: [packages/mdast-plus/src/formats/html.ts:9](https://github.com/isdk/mdast-plus.js/blob/c94d215035e579925cf60814f0a5c05c543ca784/src/formats/html.ts#L9)
+
+Unified plugin/configuration for HTML format.
+Includes mdast-to-hast conversion, sanitization (with table span support), and stringification.
+
+## Parameters
+
+### this
+
+`any`
+
+## Returns
+
+`void`

package/docs/functions/markdownFormat.md

@@ -0,0 +1,24 @@
+[**@isdk/mdast-plus**](../README.md)
+
+***
+
+[@isdk/mdast-plus](../globals.md) / markdownFormat
+
+# Function: markdownFormat()
+
+> **markdownFormat**(`this`): `void`
+
+Defined in: [packages/mdast-plus/src/formats/markdown.ts:10](https://github.com/isdk/mdast-plus.js/blob/c94d215035e579925cf60814f0a5c05c543ca784/src/formats/markdown.ts#L10)
+
+Unified plugin/configuration for Markdown format.
+Includes GFM, directives, math, and frontmatter.
+
+## Parameters
+
+### this
+
+`any`
+
+## Returns
+
+`void`

package/docs/functions/mdast.md

@@ -0,0 +1,27 @@
+[**@isdk/mdast-plus**](../README.md)
+
+***
+
+[@isdk/mdast-plus](../globals.md) / mdast
+
+# Function: mdast()
+
+> **mdast**(`input`): [`FluentProcessor`](../classes/FluentProcessor.md)
+
+Defined in: [packages/mdast-plus/src/pipeline.ts:184](https://github.com/isdk/mdast-plus.js/blob/c94d215035e579925cf60814f0a5c05c543ca784/src/pipeline.ts#L184)
+
+Entry point for the fluent mdast-plus API.
+
+## Parameters
+
+### input
+
+`any`
+
+The input content (string or mdast tree)
+
+## Returns
+
+[`FluentProcessor`](../classes/FluentProcessor.md)
+
+A FluentProcessor instance

package/docs/globals.md

@@ -0,0 +1,33 @@
+[**@isdk/mdast-plus**](README.md)
+
+***
+
+# @isdk/mdast-plus
+
+## Classes
+
+- [FluentProcessor](classes/FluentProcessor.md)
+
+## Interfaces
+
+- [ConvertResult](interfaces/ConvertResult.md)
+- [MdastAsset](interfaces/MdastAsset.md)
+- [MdastDataOrigin](interfaces/MdastDataOrigin.md)
+- [MdastFormatDefinition](interfaces/MdastFormatDefinition.md)
+- [MdastMark](interfaces/MdastMark.md)
+- [MdastPlugin](interfaces/MdastPlugin.md)
+- [MdastReader](interfaces/MdastReader.md)
+- [MdastSub](interfaces/MdastSub.md)
+- [MdastSup](interfaces/MdastSup.md)
+- [MdastTransformer](interfaces/MdastTransformer.md)
+- [MdastWriter](interfaces/MdastWriter.md)
+
+## Type Aliases
+
+- [Stage](type-aliases/Stage.md)
+
+## Functions
+
+- [htmlFormat](functions/htmlFormat.md)
+- [markdownFormat](functions/markdownFormat.md)
+- [mdast](functions/mdast.md)