本文档规范了 html-gen doc 子命令支持的 Markdown 语法子集。
遵循本规范的 .md 文件可被正确渲染为方案B 文档阅读 HTML。
一、标题
语法
# 一级标题
## 二级标题
### 三级标题
规则
| 规则 |
说明 |
示例 |
# 后必须有空格 |
无空格不识别 |
#标题 ❌ → #标题 渲染为段落 |
| 最多 3 级 |
#### 降级为段落 |
四级及更多需用列表或分段 |
| 自动生成锚点 |
slug 化处理，中英文支持 |
# 你好 World → id=你好-world |
| 自动加入 TOC |
仅 h2/h3，h1 不加入 |
h1 作为文档标题单独显示 |
| 全局行内格式 |
标题中 bold ` code ` 有效 |
## 重点 章节 支持 |
最佳实践
- 文档仅一个
# 文档标题，用作页面标题
## 作为章节分隔，### 作为子节- 不要跳级（
# → ### 略过 ##）
二、段落与行内格式
语法
普通文字段落会自动包裹在 `<p>` 标签中。
支持 **加粗**、*斜体*、`行内代码` 和 [链接](https://example.com)。
规则
| 格式 |
写法 |
渲染结果 |
| 加粗 |
文字 |
文字 |
| 斜体 |
文字 |
文字 |
行内代码 |
` 代码 ` |
代码 |
| 链接 |
文字 |
文字 |
注意事项
** 必须成对出现，不成对会被当作普通文本` `` 必须成对出现，不成对也会被当作普通文本- 斜体
* 和加粗
- 链接 url 必须是完整 URL（含
https://），相对路径不自动补全
- 以上行内格式在
<pre><code> 内无效 — 代码块中的 bold 保持原样
三、围栏代码块
语法
```python
def hello():
print("Hello")
```
规则
| 规则 |
说明 |
| 重音符号 |
必须用反引号 ` `，不支持 ~~~` |
| 最小 3 个 |
` 及以上 |
| 语言标识 |
开 fence 后跟语言名，如 `python |
| 关闭 |
关闭行必须 只有反引号，不可附带其他文字 |
| 嵌套 |
用更多反引号作为外层 fence |
嵌套示例
要在代码块内展示 ` ，外层 fence 用 4 反引号：
````
```
代码块语法示例
```
````
常见错误
| 错误写法 |
后果 |
正确写法 |
` 代码块文字` |
被解析器视为关闭行，代码块提前中断 |
关闭行后另起一行写文字 |
代码块内 ` ` 文字` |
同上一 |
外层用 4 反引号 ` `` ` |
用 ~~~ 围栏 |
不识别，当普通文本 |
用 ` |
四、表格
语法
| 列A | 列B | 列C |
|:---|:---|:---:|
| 左对齐 | 左对齐 | 居中对齐 |
| **加粗** | `code` | [链接](url) |
规则
| 规则 |
说明 |
| 行首 |
每行必须以 `\ |
` 开头 |
| 分隔行 |
第二行 `\ |
:---\ |
:---\ |
:---:\ |
` 标记对齐方式 |
| 对齐 |
:--- 左对齐、:---: 居中对齐、---: 右对齐 |
| 行内格式 |
bold ` code link` 在表格内均有效 |
| 空白表格 |
无数据行的表格渲染为空
|
常见错误
| 错误写法 |
后果 |
| 行首无 `\ |
` |
不被识别为表格 |
| 缺少分隔行 |
首行被当表头，后续行全当数据行 |
| 单行表格 |
渲染为
五、列表
语法
- 无序列表项 1
- 无序列表项 2
1. 有序列表项 1
2. 有序列表项 2
规则
| 规则 |
说明 |
| 无序 |
- 行首 + 短横 + 空格 |
| 有序 |
1. 行首 + 数字 + . + 空格 |
| 嵌套 |
不支持缩进嵌套，需扁平化组织 |
| 行内格式 |
bold ` code link` 在列表项内均有效 |
| 连续识别 |
相邻列表项自动合并到同一
|
常见错误
| 错误写法 |
后果 |
正确写法 |
* item |
被 inline_format 识别为斜体 |
- item |
-item 无空格 |
不识别 |
- item |
- item 有缩进 |
不识别嵌套 |
用扁平列表 |
六、分隔线
语法
---
---
---
规则
| 规则 |
说明 |
| 连续 3+ 短横 |
--- 及以上 |
| 前后空行 |
建议前后都有空行，否则可能被段落吞并 |
| 其他符号 |
* === 不识别 |
七、引用与 Callout
语法
> 普通引用
> **Note:** 提示信息
> **Warning:** 警告信息
> **Tip:** 小技巧
> **Danger:** 危险操作
规则
| 类型 |
写法 |
渲染 |
颜色 |
| 普通引用 |
> 文字 |
|
钴蓝边框 |
| Note |
> Note: 文字 |
|
🔵 钴蓝 |
| Tip |
> Tip: 文字 |
|
🟢 绿色 |
| Warning |
> Warning: 文字 |
|
🟡 黄色 |
| Danger |
> Danger: 文字 |
|
🔴 红色 |
关键词支持
| 语言 |
支持的关键词 |
| 中文 |
注意 / 提示 / 警告 / 危险 |
| 英文 |
Note / Tip / Warning / Danger / Caution |
| 冒号位置 |
Note: / 注意： 均支持 |
常见错误
| 错误写法 |
后果 |
> Note (无冒号) |
识别为普通引用 |
> ⚠️ 文字 |
无 ** 包裹 → 普通引用 |
| 多行引用 |
仅行首识别，后续行需单独写 > |
八、元信息自动计算
html-gen doc 在生成时自动注入元信息：
| 项目 |
来源 |
格式 |
| 路径 |
文件绝对路径 |
~/相对路径 |
| 创建时间 |
文件 st_ctime |
YYYY-MM-DD HH:mm |
| 编辑时间 |
文件 st_mtime |
YYYY-MM-DD HH:mm |
| 字数 |
len(text.split()) |
千分位 |
| 阅读时长 |
字数 / 200 |
N 分钟 |
九、不支持的语法（需避免）
| 语法 |
原因 |
替代方案 |
#### 四级标题 |
渲染器限制 |
用 粗体 或列表 |
#h1 无空格 |
格式要求 |
加空格 |
~~~ 代码围栏 |
渲染器限制 |
用 ` |
!图片 |
手写渲染器不解析 |
外链图片暂不支持 |
| HTML 标签混写 |
内容已被 textContent 解析 |
在 JSON 中注入或提交 issue |
| 4 空格缩进代码块 |
渲染器限制 |
用围栏代码块 |
任务列表 - [ ] |
渲染器限制 |
用表格或纯列表 |
脚注 [^1] |
渲染器限制 |
用括号标注 |
删除线 ~~text~~ |
渲染器限制 |
暂不支持 |
自动链接 |
渲染器限制 |
用 text 标准链接 |
十、快速参考卡
# 文档标题
## 章节标题
### 小节标题
**加粗** *斜体* `行内代码` [链接](https://)
```python
def hello():
pass
Note:提示信息
🔗 参考链接
- https://example.com
|