用途:该技能基于 render-markdown,提供一份在生产环境部署 Markdown 渲染前逐项执行的检查清单,覆盖博客、文档站与用户内容渲染场景。
主要能力:
- 信任边界检查:要求将每个 Markdown 来源分类为可信或不可信;不可信输入不得进入 allowHtml、未审计的扩展 renderHtml 钩子或未审计的高亮器。需分离可信与不可信入口,并对不可信内容关闭可信回调,强制执行链接、图片与最终 HTML 策略。
- 高亮检查:高亮回调只返回转义后的代码内容,不返回完整的 <pre><code> 树;渲染器拥有 <pre><code>,回调仅提供 code 元素的可信内容。高亮应在摄取、构建或服务端渲染时执行。
- 兼容性检查:用实际内容语料验证,而非仅依赖 CommonMark 示例;需验证确定性输出,相同源码与选项必须产生相同的序列化 AST 与 HTML。
- 性能与缓存检查:使用最终解析选项解析一次并缓存 MarkdownDocument,缓存键需带版本;稳定内容不应每请求重新解析。同时执行包体积预算检查。
- 发布检查:运行完整包门禁 pnpm run verify,覆盖测试、类型检查、构建、文档校验、一致性核算、体积、基准与 npm dry run。
必要用法示例: MARKDOWN_CORPUS_DIRS=../site/src/blog:../site/docs pnpm run test:corpus pnpm run corpus:audit:tanstack pnpm run corpus:audit:external pnpm run size pnpm test -- tests/bundle-size.test.ts pnpm run verify
常见错误:对不可信 Markdown 启用 allowHtml(allowHtml 不是消毒步骤);高亮器返回完整容器或未转义输出;把默认行为当作消毒器;假设完整 CommonMark 行为;对未变内容重复解析;向 React 注入 HTML 字符串;期望围栏元数据自动高亮。
限制:该包实现的是文档化的 docs/blog 语法配置,并非完整 CommonMark、GFM、MDX 或任意插件行为;核心转义与协议过滤不强制执行应用特定的外链、图片或最终 HTML 策略。具体版本、收费与平台信息暂未提供。