用途
本技能建立在 render-markdown 之上，用于为 @tanstack/markdown 实现自定义 Markdown 扩展。使用前应先阅读 render-markdown，了解解析器选项、文档 AST 与渲染器行为。
主要能力
- 块级解析器（parseBlock）：实现有边界的块解析器并返回标准 ComponentNode。parseBlock 在内置块解析之前运行，嵌套的 parseBlocks 共享父级深度预算与标题 slugger。
- 行内节点转换（transformInline）：接收内置行内节点，返回确定性的替换数组。
- 文档转换（transformDocument）：在块与脚注完成后运行，可返回新文档或修改现有文档，用于派生文档元数据（如标题列表）。
- HTML 钩子（renderHtml）：仅用于 HTML 输出，返回的字符串被视为可信且 HTML 专用；嵌套标准节点仍会转义，因为它们使用 context.renderBlock。
- 可移植自定义元素：通过 commentComponentsExtension 的 transformComponent 发出可移植的自定义元素（如 docs-panel），React 与 Octane 可通过 components 映射替换发出的标签。
使用方式
定义 MarkdownExtension 对象，包含 name 以及 parseBlock、transformInline、transformDocument、renderHtml 等钩子，然后将其传入 parseMarkdown 的 extensions 选项与 renderHtml 的 extensions 选项。示例代码展示了 notes 扩展、important-inline 行内转换、top-level-headings 文档转换、compact-callout-html 渲染钩子以及 commentComponentsExtension 的用法。
适用场景
- 添加确定性的自定义 Markdown 语法（如 :::note 块）。
- 对已解析的行内节点做确定性替换。
- 解析后派生文档元数据。
- 为 HTML 输出定制渲染。
- 发出可移植的 ComponentNode，供 React 或 Octane 通过组件映射替换。
限制与注意事项
- 声明块必须消费：返回节点只会前进一行，除非用 consume 记录完整的所属块。
- 扩展顺序：扩展按数组顺序运行，宽泛的解析器可能遮蔽特定解析器的语法（如引用行解析器遮蔽 callout 语法），应将通用解析器放在后面。
- HTML 钩子不适用于框架节点：renderHtml 钩子在 React 或 Octane 中不会运行，可移植路径是 ComponentNode 加发出标签的组件映射。
- 解析后不可更改扩展：文档转换会持久保存在 AST 中，但 HTML 渲染钩子需要在渲染时再次传入扩展。
- 信任边界：富输出优先使用 ComponentNode 加应用组件；allowHtml、扩展 HTML 字符串与高亮标记应视为显式可信边界。
- 解析性能与选项时机：在缓存 MarkdownDocument 之前应用解析器选项与文档转换扩展；渲染时选项无法重建缺失的解析行为。
- 渲染器一致性：核心节点在 HTML、React 与 Octane 之间保持等价；HTML 钩子与框架组件替换会有意离开该一致性边界。
相关技能
- render-markdown：AST、解析器选项与标准渲染器。
- docs-features：第一方扩展实现与元数据契约。
- react-rendering：发出组件标签的 React 映射。
- octane-rendering：Octane ComponentBody 映射。
- production-pipelines：信任、兼容性与打包审计。