Custom Extensions
该技能建立在 render-markdown 之上,建议先阅读它,以了解解析器选项、文档 AST 和渲染器行为。
用途
用于在 @tanstack/markdown 中实现自定义 Markdown 扩展,覆盖块级与行内源码解析、行内与文档级转换、HTML 钩子,以及可移植的块级与行内组件输出。
主要能力
- 块级解析:通过
parseBlock(context)实现有边界的块解析器,返回标准ComponentNode。它可读取context.lines与context.index,并用context.consume(...)声明所拥有的完整块范围,嵌套调用context.parseBlocks(...)会共享父级深度预算与标题 slugger。 - 行内源码解析:使用
inlineParser: { markers, parse(context) }处理需要原始源码字符的语法。markers是字面量首字符组成的字符串;上下文提供source、UTF-16index、options、inLink和parseInline(value),并共享当前深度与扫描预算。返回{ node, length },其中 node 为一个标准InlineNode,length 为在界内的正整数;返回undefined表示放弃。非法长度会抛出RangeError。 - 行内节点转换:
transformInline(nodes)可修改已解析节点,接收内置行内节点与 inlineParser 返回的扩展节点,并返回确定性的替换数组。它无法区分转义的开头标记与普通文本开头,也无法恢复原始 Markdown 写法。 - 自定义行内 UI:返回
type: 'inlineComponent'的InlineComponentNode,带 name、attributes、inline children,以及可选tagName和字符串properties。它使用与块级ComponentNode相同的 emitted-tag 组件映射,但默认输出<span>,而不是<md-comment-component>。 - 文档级转换:
transformDocument(document)在块和脚注完成后运行,可返回新文档或修改现有文档,例如从顶层标题派生文档元数据(document.headings)。 - HTML 钩子:
renderHtml(node, context)仅用于 HTML 输出,返回的字符串被视为可信;嵌套标准节点通过context.renderBlock渲染并保持转义。 - 可移植自定义元素:通过 commentComponentsExtension 的
transformComponent(node)修改组件节点的tagName与properties,React 和 Octane 可通过 components 映射替换输出的标签。
使用方式
定义扩展对象后,将其放入 extensions 数组,并同时传给 parseMarkdown 与 renderHtml:
const extensions = [notesExtension()]
const document = parseMarkdown(source, { extensions })
const html = renderHtml(document, { extensions })
扩展按数组顺序执行。文档转换结果会保留在 AST 中,但 HTML 渲染钩子需要在渲染时再次提供该扩展。
适用场景
- 自定义块语法,例如
:::note这类围栏块。 - 需要原始源码字符的行内语法扩展。
- 对已解析行内节点做确定性改写。
- 从文档结构派生元数据(如标题列表)。
- 为 HTML 输出定制标签,或通过组件节点向 React/Octane 输出可移植自定义元素。
限制与注意事项
- 转义与代码段优先:转义和代码段优先于钩子;钩子不会在代码、图片替代文本或链接目标中运行,但会在强调与链接标签中运行。创建自动链接时应尊重
inLink。索引是当前行内容器内的局部索引,范围不能跨越外层行内或块边界。钩子分发有预算,但回调本身被信任,应避免重复的后缀扫描。返回的 AST 节点被信任,需自行校验 URL 与组件元数据。 - 块解析需 consume:仅返回节点只前进一行,除非
consume记录完整拥有的块。 - 解析器顺序:宽泛的解析器(如引用行解析)若排在特定解析器(如 callouts)之前,可能屏蔽后者语法。
- 框架渲染不使用 HTML 钩子:renderHtml 钩子在 React 或 Octane 中不会运行;可移植路径是组件节点加 emitted-tag 组件映射。
- 渲染时需重新提供扩展:HTML 渲染钩子依赖渲染时传入的 extensions。
- 信任边界:建议优先使用块级或行内组件节点加应用组件实现富输出;allowHtml、扩展 HTML 字符串和高亮器标记应视为显式信任边界。
相关技能
- render-markdown:AST、解析器选项与标准渲染器。
- docs-features:一方扩展实现与元数据合约。
- react-rendering:emitted 组件标签的 React 映射。
- octane-rendering:Octane ComponentBody 映射。
- production-pipelines:信任、兼容性与打包审计。