# Markdown To HTML
> 将 Markdown 文档转换为独立 HTML 页面。复杂 Mermaid 用 sidecar（.figures/） 分层卡片替代；推荐两阶段：先基本 sidecar + md2html build，再按需打磨单张图。 Use when the user asks to convert markdown to HTML, md2html, sidecar, customfig, or mentions "md 转 html", "生成 html", "导出 html", "markdown to html".
- Skill: `zxremail/markdown-to-html` (Agent Skill, multi-file: 19 files)
- Install (CLI): `npx skillmds@latest add zxremail/markdown-to-html`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zxremail/markdown-to-html/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: zxremail (https://skillmd.com/u/zxremail)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/zxremail/markdown-to-html
---
# Markdown 转 HTML 规范
选 sidecar 布局（深色卡片 / 时序 / 时间表 / 胶囊图）前，先读 `diagram-style-catalog`。本 skill 管 HTML 交卷与 §7.6 深色分层卡片；浅色行动胶囊走 `layer-action-capsule-diagram`。
## 目录 • Markdown 转 HTML 规范
- [1. 基本结构](#1-基本结构)
- [1.1 正文目录锚点必须兼容 GitHub slug](#11-正文目录锚点必须兼容-github-slug)
- [2. Mermaid 图表处理](#2-mermaid-图表处理)
- [2.1 正常情况](#21-正常情况)
- [2.2 触发降级的条件（必须自动判断）](#22-触发降级的条件必须自动判断)
- [2.3 小流程图不要拉满栏宽](#23-小流程图不要拉满栏宽)
- [3. 分层彩色卡片布局规范](#3-分层彩色卡片布局规范)
- [3.1 配色体系（深色主题）](#31-配色体系深色主题)
- [3.2 层级配色分配](#32-层级配色分配)
- [3.3 HTML 结构模板](#33-html-结构模板)
- [3.4 CSS 基础类](#34-css-基础类)
- [3.5 复杂布局扩展](#35-复杂布局扩展)
- [4. `` 注入机制](#4-template-注入机制)
- [5. 文件命名](#5-文件命名)
- [6. 不要做的事](#6-不要做的事)
- [7. CLI 工具（md2html）](#7-cli-工具md2html)
- [7.1 安装](#71-安装)
- [7.2 常用命令](#72-常用命令)
- [7.3 Sidecar 是什么](#73-sidecar-是什么)
- [7.4 Sidecar 目录约定](#74-sidecar-目录约定)
- [7.5 两阶段工作流（推荐）](#75-两阶段工作流推荐)
- [7.6 布局模式速查](#76-布局模式速查)
- [7.7 命令速查](#77-命令速查)
---
将 Markdown 文档转换为可在浏览器中独立打开的 HTML 页面，支持 Mermaid 渲染，并在 Mermaid 表达力不足时自动降级为分层彩色卡片布局。
---
## 1. 基本结构
生成的 HTML 必须是**单文件、零依赖**的独立页面（CDN 引用除外）：
```html
文档标题
```
要求：
- 深色主题（GitHub Dark 风格），参考色板见下方"配色体系"
- 左侧固定侧边栏（自动从 h1/h2 生成目录）
- 响应式布局（`@media max-width:900px` 时侧边栏收起）
- Markdown 内容通过 `marked.js` 在客户端解析渲染
- 正文 `md-toc` 目录链接必须能跳转，见 [§1.1](#11-正文目录锚点必须兼容-github-slug)
### 1.1 正文目录锚点必须兼容 GitHub slug
`.md` 正文目录由 `md-toc` 生成，锚点是 **github-slugger**（与 VS Code / GitHub 预览一致），例如 `[1. 怎么验证](#1-怎么验证)`、`[2.1 正常情况](#21-正常情况)`。侧栏 TOC 仍用 `h-1` / `h-2-1`。
标题必须**两套 id 都有**，缺 GitHub slug 时正文目录会点了没反应：
```html
1. 怎么验证
```
实现已写入模板，**不要改回去**：
| 文件 | 作用 |
|------|------|
| `md2html/templates/anchor.js` | `mdGithubSlug` / `mdHeadingHtml` / `mdFindHashTarget` |
| `md2html/templates/runtime.js` | heading 渲染与正文 `#` 点击走上述函数 |
| `md2html/builder.py` | 把 `anchor.js` **拼在** `runtime.js` 前面再嵌入页面 |
改这三处后必须跑：
```bash
node ~/.cursor/skills/markdown-to-html/tests/test_anchor.js
```
正文 `#` 点击：先解析目标，找不到就**不要** `preventDefault`（否则默认锚点也被吞掉）。
## 2. Mermaid 图表处理
### 2.1 正常情况
Markdown 中的 ` ```mermaid ` 代码块由 `mermaid.js` 在客户端渲染，无需特殊处理。
**源 `.md` 里的图必须已经是深彩色**：HTML 全局 `theme:'dark'` **不能代替**节点 `style`/`classDef`。若源图是默认浅色节点，导出页在暗色主题里同样难看。写或改源文档时遵循 **`markdown-export`** §5 与 **`mermaid-flowchart-layout`** §0。
写图前再读三遍：
1. 所有的 Mermaid 图表都使用深彩色配色方案，以便适合在暗色主题环境中查看，同时保持良好的对比度和可读性。
2. 所有的 Mermaid 图表都使用深彩色配色方案，以便适合在暗色主题环境中查看，同时保持良好的对比度和可读性。
3. 所有的 Mermaid 图表都使用深彩色配色方案，以便适合在暗色主题环境中查看，同时保持良好的对比度和可读性。
### 2.2 触发降级的条件（必须自动判断）
遇到以下任一情况时，**禁止使用 Mermaid**，必须改用分层彩色卡片布局：
| 信号 | 说明 |
|------|------|
| 节点 > 15 个 | 单个 Mermaid 代码块中节点数超过 15 |
| 层级 > 4 层 | 架构图存在 4 层以上的纵向分层 |
| 并列 subgraph > 3 | 同一层级有 3 个以上并列 subgraph |
| 节点含多行文本 | 节点内需要标题 + 描述 + 注释等多行信息 |
| 双向/复杂连接 | 层间存在大量双向箭头或交叉连接 |
| 表格/列表嵌套 | 节点内需要展示列表或表格形式的子项 |
**判断原则**：如果 Mermaid 渲染后可能出现节点重叠、文字截断、箭头交叉、需要横向滚动，就必须降级。
### 2.3 小流程图不要拉满栏宽
`useMaxWidth: true`（或 CSS `width:100%`）会把小 `flowchart` 拉满正文栏；正方形 viewBox 跟着变成近一屏高，四周大片空白。
**HTML 模板（已写入 `base.css` / `anchor.js` / `runtime.js`，不要改回去）：**
```css
.mermaid svg{
max-width:100% !important;
width:auto !important;
height:auto !important;
display:block;
margin:0 auto;
}
```
```js
flowchart:{htmlLabels:true,curve:'basis',useMaxWidth:false,nodeSpacing:20,rankSpacing:32,padding:8}
```
**Markdown 源里的小图**（预览不走上述 CSS）在 fence 内写：
```
%%{init: {'theme':'dark','flowchart':{'useMaxWidth':false,'nodeSpacing':16,'rankSpacing':28,'padding':8}}}%%
flowchart TB
```
禁止 `.mermaid svg { max-width: none }`。宽架构图仍可靠 `overflow-x:auto` 横向滚动，不要靠撑满栏宽放大节点。
## 3. 分层彩色卡片布局规范
当 Mermaid 不适用时，使用纯 HTML/CSS 绘制分层架构图。
### 3.1 配色体系（深色主题）
```css
:root {
--bg:#0d1117; --panel:#161b22; --panel2:#21262d; --border:#30363d;
--text:#c9d1d9; --muted:#8b949e; --dim:#484f58;
--blue:#58a6ff; --bluebg:#0d2137; --bluetxt:#79c0ff;
--green:#3fb950; --greenbg:#122117; --greentxt:#7ee787; --greenborder:#238636;
--orange:#f0883e; --orangebg:#1a150d; --orangetxt:#ffcc80;
--purple:#a371f7; --purplebg:#1a1428; --purpletxt:#d2a8ff; --purpleborder:#6e40c9;
--red:#f85149; --redbg:#2d1215; --redtxt:#ffa198; --redborder:#da3633;
}
```
### 3.2 层级配色分配
每一层使用不同颜色主题，从上到下推荐：
| 层级 | 语义 | 颜色 | border | 背景 | 文字 |
|------|------|------|--------|------|------|
| 应用层 | 用户态进程 | 灰 | `--dim` | `--panel2` | `--muted` |
| 库/SDK 层 | 链接库 | 蓝 | `--blue` | `--bluebg` | `--bluetxt` |
| 服务层 | Daemon | 橙 | `--orange` | `--orangebg` | `--orangetxt` |
| 内核层 | 驱动/模块 | 紫 | `--purple` | `--purplebg` | `--purpletxt` |
| 硬件层 | FPGA/芯片 | 灰暗 | `--dim` | `--panel` | `--muted` |
| 固件层 | MCU/FW | 橙虚线 | `--orange` dashed | `--orangebg` | `--orangetxt` |
| 管理面 | 监控/告警 | 红 | `--red` | `--redbg` | `--redtxt` |
| 数据面 | 高速数据通路 | 绿 | `--green` | `--greenbg` | `--greentxt` |
如果实际层级语义与上表不匹配，可灵活选择颜色，但必须保持**相邻层颜色有明显区分**。
### 3.3 HTML 结构模板
每一层使用 `.layer` 容器：
```html
```
### 3.4 CSS 基础类
```css
.customfig {
background: #0d1117; border-radius: 12px; padding: 28px; margin: 18px 0;
font-family: "SF Mono","Cascadia Code",monospace; font-size: 13px;
line-height: 1.55; color: var(--text); border: 1px solid var(--border);
}
.layer {
border: 2px solid var(--dim); border-radius: 8px;
padding: 12px 14px; margin: 0 0 4px 0; background: #0d1117;
}
.layer-header {
display: flex; justify-content: space-between;
align-items: center; margin-bottom: 10px; gap: 10px;
}
.layer-label { font-weight: bold; font-size: 14px; }
.layer-sub { color: var(--dim); font-size: 11px; }
.layer-body { display: flex; gap: 6px; flex-wrap: wrap; justify-content: center; }
.node {
padding: 6px 12px; border-radius: 5px; font-size: 12px;
display: inline-block; line-height: 1.4;
}
.node .note { font-size: 10px; opacity: .8; }
.arrow { text-align: center; color: var(--dim); margin: 2px 0; font-size: 11px; }
```
### 3.5 复杂布局扩展
当单层内有子分组（如"管理面 vs 数据面"并列）时，使用 flex 分栏：
```html
```
当需要网格布局（如多列功能矩阵）时，使用 CSS Grid：
```css
.layer-body.grid-4 {
display: grid; grid-template-columns: repeat(4, 1fr); gap: 8px;
}
```
## 4. `` 注入机制
将自绘图放在 `` 标签中，通过占位符注入 Markdown 渲染结果：
1. 在 Markdown 源文本中放置占位符：``
2. 在 HTML 的 `` 中定义图形
3. JS 渲染完成后，将占位符替换为 template 内容
```javascript
document.querySelectorAll('[data-figure]').forEach(el => {
const tpl = document.getElementById(el.dataset.figure);
if (tpl) el.replaceWith(tpl.content.cloneNode(true));
});
```
## 5. 文件命名
- 与源 Markdown 同名，扩展名改为 `.html`
- 放在与源文件相同的目录下
- 例：`architecture-design.md` → `architecture-design.html`
- 工作区根存在 `ai.cursor/` 且正在**新建**说明文档时，**REQUIRED：** 先按 **`ai-cursor-doc-output`** 放置源 md，再把 html / sidecar 放在**同一知识库子目录**；不要单独把 `.html` 写到仓库根「方便打开」
## 6. 不要做的事
- **不要**把所有图都降级为卡片——简单的 Mermaid 图保留 Mermaid
- **不要**把 `.mermaid svg` 设为 `max-width:none` 或默认 `useMaxWidth:true`——小流程图会被拉满栏宽
- **不要**使用外部 CSS 文件——所有样式内嵌
- **不要**使用外部图片——图表全部用 HTML/CSS 绘制
- **不要**生成后不检查——生成后应提醒用户在浏览器中预览确认
- **不要**只给标题 `id="h-N"`、丢掉 GitHub slug——正文目录（`#1-怎么验证`）会无法跳转；**不要**从 `builder.py` 拿掉 `anchor.js` 拼接
---
## 7. CLI 工具（md2html）
本技能目录下提供可复用的 Python CLI，Agent 与人工均可调用。
### 7.1 安装
```bash
pip install -e ~/.cursor/skills/markdown-to-html
# 无 pip：~/.cursor/skills/markdown-to-html/bin/md2html build doc.md
```
### 7.2 常用命令
见 [§7.7 命令速查](#77-命令速查)。工作流见 [§7.5 两阶段工作流](#75-两阶段工作流推荐)。
### 7.3 Sidecar 是什么
**Sidecar**（边车）：与主 Markdown **配套挂载**、**不写入 `.md` 正文**的 HTML 图稿目录。
```
doc.md ← 主文档
doc.figures/ ← sidecar 目录
mermaid-0.html ← 替换第 0 个「应降级」的 Mermaid 块
mermaid-1.html
extra.css ← 可选，追加页面样式
```
`md2html build` 将 sidecar 合并进单页 HTML 的 ``，正文通过 `customfig:mermaid-N` 或 `` 引用。
### 7.4 Sidecar 目录约定
| 规则 | 说明 |
|------|------|
| 默认路径 | 与 `doc.md` 同级：`doc.figures/` |
| Mermaid 替换 | 第 N 个应降级块 → `mermaid-N.html`（从 0 起） |
| 自定义图 | 任意 `fig-id.html`，Markdown 用 `` |
| extra.css | 追加页面内嵌样式。长表冻结标题行用 **freezing-html-table-headers**（页面级 sticky，禁止 `overflow`+`max-height` 内嵌框） |
| 文件内容 | 片段 HTML（`.customfig` 根元素）；可含 scoped `