md-document

md-document — 长篇 Markdown 转 HTML

通用转换器——适用于 Shihipar 所述 90% 的常见场景（规范、计划、RFC、报告、说明文档）。三个标准库工具串联运行：

markdown_parser.py  →  html_renderer.py  →  interactivity_injector.py
   (md → JSON AST)    (AST + tokens → HTML)    (HTML + JS behavior)

输出为一个 .html 文件，包含固定目录、搜索筛选器、滚动定位、代码复制按钮，以及用户的 12 个衍生品牌令牌。外部资源仅限 Google Fonts CSS 和 Prism.js CDN。

何时调用

症状	操作
markdown-html-orchestrator 将输入路由为 DOCUMENT	调用此技能
用户直接运行 /cs-md-document <path>.md	调用此技能
用户说“将此规范／报告／RFC／计划转换为 HTML”	调用此技能
输入是代码审查（包含 ```diff 代码块）	改为路由到 md-review
输入是幻灯片（具有明显的 --- 分隔线）	改为路由到 md-slides
输入少于 100 行	拒绝（Shihipar 的阈值——此时 Markdown 仍是更好的选择）
尚未接入设计系统	拒绝，并提示 /cs-design-system

流程

# 1. Parse markdown → JSON AST
python3 markdown-html/skills/md-document/scripts/markdown_parser.py \
    --input <path>.md --output sections.json

# 2. Render AST + design-system config → single-file HTML
python3 markdown-html/skills/md-document/scripts/html_renderer.py \
    --sections sections.json --output document.html

# 3. Inject lightweight JS (search, copycode, smoothscroll, scrollspy)
python3 markdown-html/skills/md-document/scripts/interactivity_injector.py \
    --file document.html \
    --features search,copycode,smoothscroll,scrollspy

或者使用一体化方式（示例渲染）：

python3 markdown-html/skills/md-document/scripts/html_renderer.py --sample \
  | python3 markdown-html/skills/md-document/scripts/interactivity_injector.py \
      --file /dev/stdin --output document.html

渲染内容

足以处理 Agent 生成内容的 CommonMark 子集：

• 标题 H1-H6（每个 H2 及以上标题都会获得锚点 ID 并加入目录）
• 带行内 粗体 / 斜体 / 代码 / 链接 / 的段落
• 围栏代码块（```python），按需使用 Prism.js 高亮
• 支持逐列对齐的 GFM 表格
• GFM 提示框（> [!NOTE]、> [!TIP]、> [!IMPORTANT]、> [!WARNING]、> [!CAUTION]）
• 引用块、有序列表和无序列表（单层）、水平分隔线

不支持：嵌套列表、行内 HTML、脚注、定义列表、任务列表复选框（作为纯文本渲染）、引用式链接。

硬性规则

1. 拒绝少于 100 行的输入。 低于此阈值时应优先使用 Markdown（Shihipar）。
2. 未接入设计系统时拒绝处理。 config_loader.setup_completed() 必须返回 True。否则提示 /cs-design-system。
3. 输出为单个文件。 所有 CSS 和 JS 均内联。外部资源仅限 fonts.googleapis.com 和 cdn.jsdelivr.net（Prism）。其他任何外部资源都属于回归。
4. 自定义设置必须改变行为。 design_style=editorial 会生成宽 720px、行高 1.75 的布局；playful 会为提示框添加圆角和阴影；technical 会采用紧凑布局，代码字号为 0.875rem。均已通过冒烟测试。
5. 令牌符合 WCAG。 继承设计系统的 WCAG AA 调色板——正文文本对比度 ≥ 4.5:1，链接颜色经过迭代调整，达到 4.5:1。
6. 注入操作幂等。 重复注入交互功能不会产生变化（通过标记检查）。使用不同的 design_style 重新渲染也能正常工作。

追问问题库（Matt Pocock 式审问原则）

1. 这份文档的用途是什么——浏览、决策还是深入阅读？ 建议：明确说明；内容密度应与用途相符。参考：Shihipar；Tufte 的 Envisioning Information。
2. 采用固定侧边栏目录，还是可折叠的顶部目录？ 建议：超过 800 个词或有 4 个以上 H2 标题时采用固定侧边栏；较短、优先面向移动设备的文档采用可折叠顶部目录。参考：NN/g 的 TOC Best Practices（2023）。
3. 启用全部四项交互功能，还是只启用其中一部分？ 建议：全部启用——每项的开销都不超过约 1 KB。参考：Wattenberger 的 Why React isn't great for actually building websites。
4. 代码主题采用浅色、深色还是自动？ 建议：自动（遵循操作系统的 prefers-color-scheme）。参考：WCAG 2.2 §1.4.3。
5. 文档是否有明确的 H1 标题？ 建议：有——H1 会成为页面的 <title>，且不会加入目录。

与以下工具的区别

• md-review——该转换器会渲染差异代码块和带严重程度标签的边栏注释。此转换器渲染正文、表格、代码和提示框。
• md-slides——该转换器按 --- 分隔线拆分幻灯片。此转换器渲染一份连续文档。
• marketing/landing/——该工具从头生成落地页（不输入 Markdown）。此工具转换现有 Markdown。

输出产物

{default_output_dir}/doc-{slug}.html（路径由编排器的 output_path_resolver.py 解析；默认情况下，文件名冲突时会添加 -2、-3 等后缀）。

参考资料

• Shihipar — Claude Code HTML 输出（Medium，2026 年）
• Tufte — Envisioning Information（1990 年），第 2 章“微观／宏观阅读”
• NN/g — 目录最佳实践（2023 年）
• WCAG 2.2 — §1.4.3 对比度，§2.4.5 多种方式
• Wattenberger — 为什么 React 并不适合实际构建网站
• 完整引文见 references/