Markdown 文档

md-document

分类编程

作者Alireza Rezvani

许可MIT

评分4.30/5

使用11.8K

md-document — 长篇 Markdown 转 HTML

通用转换器 —— 处理 Shihipar 描述的 90% 场景（规范、计划、RFC、报告、解释文档）。三个标准库工具通过流水线协作：

code

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

输出为单个 .html 文件，包含固定目录、搜索过滤、滚动监听、代码复制按钮以及用户衍生的 12 个品牌 Token。外部依赖仅限于 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 仍是最佳选择） |
| 设计系统未完成 onboarding | 拒绝，并提示 /cs:design-system |

流水线

bash

# 1. 解析 markdown → JSON AST
python3 markdown-html/skills/md-document/scripts/markdown_parser.py \
    --input <path>.md --output sections.json
2. 渲染 AST + 设计系统配置 → 单文件 HTML
python3 markdown-html/skills/md-document/scripts/html_renderer.py \
    --sections sections.json --output document.html
3. 注入轻量级 JS（搜索、代码复制、平滑滚动、滚动监听）
python3 markdown-html/skills/md-document/scripts/interactivity_injector.py \
    --file document.html \
    --features search,copycode,smoothscroll,scrollspy

或一键执行（示例渲染）：

bash

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 标准的 Token。 继承设计系统的 WCAG AA 调色板 —— 正文对比度 ≥ 4.5:1，链接经过迭代调整至 4.5:1。
6. 幂等注入。 重新注入交互功能应为无操作 (no-op)（通过标记检查）。使用不同的 design_style 重新渲染应能干净地执行。

强制性问题库 (Matt Pocock 质询法)

1. 文档用途是什么 —— 浏览、决策还是深读？ 建议：明确标注；密度随之而定。参考：Shihipar; Tufte *Envisioning Information*。
2. 采用固定侧边栏 TOC 还是可折叠顶部 TOC？ 建议：超过 800 字 / 4 个 H2 时使用固定侧边栏；较短的移动端优先文档使用可折叠顶部。参考：NN/g *TOC Best Practices* (2023)。
3. 启用全部四个交互功能，还是仅部分？ 建议：全部启用 —— 每个功能的大小均不超过 ~1 KB。参考：Wattenberger *Why React isn't great for actually building websites*。
4. 代码主题 —— 浅色、深色还是自动？ 建议：自动 (遵循 OS prefers-color-scheme)。参考：WCAG 2.2 §1.4.3。
5. 文档是否有明确的 H1 标题？ 建议：是 —— H1 将成为页面 <title> 且不包含在 TOC 中。

区别于

md-review —— 该转换器渲染 diff 块 + 带有严重程度标记的页边注。本转换器渲染正文 + 表格 + 代码 + 标注。

md-slides —— 该转换器根据 --- 分隔符将内容拆分为幻灯片。本转换器渲染为单一连续文档。

marketing/landing/ —— 该模块从零生成落地页（无 Markdown 输入）。本模块转换现有的 Markdown。

输出产物

{default_output_dir}/doc-{slug}.html (路径由编排器的 output_path_resolver.py 解析；冲突时默认添加后缀 -2, -3, …)。

参考文献

Shihipar — *Claude Code HTML output* (Medium, 2026)

Tufte — *Envisioning Information* (1990), ch. 2 "Micro/Macro Readings"

NN/g — *Table of Contents Best Practices* (2023)

WCAG 2.2 — §1.4.3 对比度, §2.4.5 多种方式

Wattenberger — *Why React isn't great for actually building websites*

完整引用请参阅 references/