技能介绍

先解决的问题

把一份几百行的 Markdown 规格、RFC 或报告直接发给通用转换链路，常见结果是：目录要么缺失，要么锚点和正文对不上；长文档在手机上找不到当前读到哪一节；代码块没有复制按钮，读者要手动框选；样式跟着某个模板走，和你自己的设计规范没关系。

md-document 面向的是这类长篇技术文档的九成常见情况，不追求把 Markdown 变成营销页。它产出单个 .html 文件，自带 sticky TOC、搜索过滤、scrollspy 和代码复制按钮，并应用由你提供的品牌色板派生出的 12 个 design tokens。

内部如何工作

核心流程是三个 stdlib Python 脚本串成一条管道：

markdown_parser.py：读取 .md，解析为 sections JSON，后续渲染不再碰原文结构。
html_renderer.py：把 AST 和 design-system config 渲染成一个 HTML 文件；也能用 --sample 走自检路径。
interactivity_injector.py：在产物上注入轻量 JS，功能按 search,copycode,smoothscroll,scrollspy 选择。

支持范围明确：GFM 表格（含列对齐）、GFM callouts（如 > [!NOTE]、> [!WARNING]）、引用块、单层有序/无序列表、分隔线，以及按需加载的 Prism.js 代码高亮。外部依赖只限制在 Google Fonts CSS 和 Prism.js CDN。

适用边界与注意点

它不做嵌套列表、HTML 内联、脚注、定义列表；任务列表的复选框会按纯文本渲染，引用式链接也不在范围内。输入应当是纯文档，不是代码评审 diff——那属于 md-review；也不负责按 --- 切分成幻灯片，那属于 md-slides。

生成前会做几项判断：文档是否超过约 800 词或 4 个 H2（超过则侧边 sticky TOC，较短则用移动端友好的折叠目录）；四种交互是否全开（推荐全开，成本都很低）；代码主题是否跟随系统 prefers-color-scheme；是否存在清晰 H1（H1 会成为页面标题，并从 TOC 中排除）。输出路径由 orchestrator 的 output_path_resolver.py 解析，默认文件名形如 doc-{slug}.html，同名时追加 -2、-3。