SuperAPI AI 工具集

custom-extensions

编程与开发

查看项目

更新于 10-16 06:58

技能介绍

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-16 index、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:信任、兼容性与打包审计。