Markdown 格式规范

本规范适用于仓库内所有 Markdown 文档（.md），涵盖站点文档、README、Issue 与 PR 描述。团队使用 Prettier 负责格式化排版、markdownlint 负责规则校验，二者配置已相互对齐（见第 12 节），先格式化后校验不会冲突。

---

1. 通用原则

• 标题统一使用 ATX 风格（#），不使用 Setext（下划线）风格。
• 使用空格缩进，禁止使用制表符（Tab）。
• 行尾不留多余空格，文件末尾保留且仅保留一个换行符。
• 标题、段落、列表、代码块、表格等块级元素之间用一个空行分隔。
• 连续空行不超过一行。

2. 标题

2.1 层级

每个文档只有一个一级标题（#），作为文档标题置于开头。标题层级逐级递增，不得跳级：

<!-- bad — 从 H2 跳到 H4 -->

## 概述

#### 细节

<!-- good -->

## 概述

### 细节

2.2 格式

# 与标题文字之间加一个空格，标题前后各留一个空行，末尾不加标点：

<!-- bad — 缺少空格、结尾带标点 -->

##概述：

<!-- good -->

## 概述

3. 段落与换行

段落之间用一个空行分隔。避免使用行尾两个空格实现硬换行；需要分行时另起段落或改用列表：

<!-- bad — 行尾空格换行（不可见、易丢失） -->
第一行␠␠
第二行

<!-- good -->
第一行

第二行

4. 列表

4.1 无序列表

统一使用连字符 - 作为项目符号，不混用 * 或 +：

<!-- bad -->
* 第一项
+ 第二项

<!-- good -->
- 第一项
- 第二项

4.2 有序列表

推荐使用递增序号 1.、2.、3.。序号会由 Prettier 自动规范，无需手动维护：

<!-- good -->

1. 第一步
2. 第二步
3. 第三步

4.3 嵌套与缩进

嵌套列表的缩进交由 Prettier 统一处理（无序列表下缩进 2 空格，有序列表下缩进 3 空格），因此 markdownlint 不再校验缩进宽度（MD007 关闭）。列表与前后正文之间留一个空行：

<!-- good -->

- 第一项
  - 子项 A
  - 子项 B
- 第二项

5. 强调

加粗使用 **，斜体使用 _（与 Prettier 输出保持一致）。不要用强调代替标题：

<!-- bad — 用加粗充当标题 -->
**配置说明**

<!-- bad — 斜体用星号、加粗用下划线 -->
这是 *斜体* 与 __加粗__。

<!-- good -->
这是 _斜体_ 与 **加粗**。

6. 代码

6.1 行内代码

函数名、变量名、文件名、命令、配置值等技术内容用反引号包裹：

<!-- good -->
运行 `bun dev` 启动开发服务器，将 `debug` 设为 `true`。

6.2 围栏代码块

使用反引号围栏（```），不使用波浪线 ~~~。必须标注语言，无合适语言时使用 text：

<!-- bad — 未标注语言 -->

```
bun install
```

<!-- good -->

```bash
bun install
```

7. 链接与图片

• 使用行内链接 [文字](url)，站内相对链接省略 .md 后缀（本站启用 cleanUrls）。
• 图片必须提供有意义的 alt 文本。

<!-- bad — 站内链接带 .md、图片缺少 alt -->
参见 [命名规范](./naming.md)。
![](/logo.svg)

<!-- good -->
参见 [命名规范](./naming)。
![SiiWay 标志](/logo.svg)

8. 表格

使用竖线表格，包含表头分隔行，单元格内容首尾各留一个空格：

<!-- good -->

| 分支    | 用途     |
| ------- | -------- |
| main    | 长期分支 |
| feature | 功能分支 |

表格无需逐列对齐字符宽度，markdownlint 不强制列宽，但要求结构完整。

9. 引用块与分隔线

• 引用块使用 >，与正文之间留空行。
• 分隔线统一使用三个连字符 ---，前后各留一个空行。

<!-- good -->

> 提示：本步骤需要管理员权限。

---

10. 内联 HTML 与 GitHub 扩展语法

• 允许在必要时使用内联 HTML 与 Vue 组件（VitePress 特性），markdownlint 已放行（MD033 关闭）。
• Markdown 示例中的说明性注释使用 HTML 注释（<!-- -->），避免渲染到页面正文。
• 优先使用 GitHub Alerts 表达提示，而非 VitePress 自定义容器或手写 HTML：

<!-- good -->
> [!NOTE]
> 推荐使用 bun 作为包管理器。

> [!WARNING]
> force push main 分支被禁止。

• Frontmatter 置于文件最顶部，使用 --- 成对包裹：

---
title: 页面标题
---

# 页面标题

11. 与标点规范的关系

Markdown 语法结构（链接、代码、列表符号等）一律使用半角字符；正文中文内容的标点遵循 标点符号使用规范。

12. 工具链：Prettier 与 markdownlint

团队使用两款工具协作，职责分明、互不冲突：

• Prettier：负责“格式化”——列表符号、斜体/加粗字符、缩进、表格对齐、空行、行尾换行等排版细节，配置见 .prettierrc。
• markdownlint：负责“规则校验”——标题层级、代码块语言、重复标题等语义规则，配置见 .markdownlint.jsonc。

相关配置文件：

• .markdownlint.jsonc：markdownlint 规则配置。
• .pymarkdown.yaml：PyMarkdown（Python 版 markdownlint）等价规则配置。
• .prettierrc：Prettier 格式化配置。

12.1 冲突规避

Prettier 会主动改写部分排版，因此 markdownlint 中所有可能与之冲突的规则，均已对齐 Prettier 的默认输出或直接关闭：

规则	配置	说明
MD003	atx	标题使用 # 风格（与 Prettier 一致）
MD004	dash	无序列表使用 -（与 Prettier 一致）
MD007	false	缩进交由 Prettier 处理，避免有序列表下冲突
MD013	false	不限制行长度（Prettier proseWrap: preserve）
MD024	siblings_only	仅禁止同级重复标题
MD026	含全角标点	标题末尾禁止标点（Prettier 不改动）
MD029	one_or_ordered	允许全 1. 或递增，避免与 Prettier 重编号冲突
MD033	false	允许内联 HTML / Vue 组件
MD035	---	分隔线使用 ---（与 Prettier 一致）
MD041	false	允许 frontmatter / 组件作为首行
MD046	fenced	代码块使用围栏风格（与 Prettier 一致）
MD048	backtick	围栏使用反引号（与 Prettier 一致）
MD049	underscore	斜体使用 _（对齐 Prettier）
MD050	asterisk	加粗使用 **（与 Prettier 一致）

.markdownlintignore 与 .prettierignore 均排除了 node_modules、构建产物等目录。

12.2 Python 版：PyMarkdown

使用 Python 工具链的成员可改用 PyMarkdown（pip install pymarkdownlnt 或 uv tool install pymarkdownlnt）替代 Node 版 markdownlint，等价配置见仓库根目录的 .pymarkdown.yaml，运行 pymarkdown scan . 时会自动加载。

NOTE

PyMarkdown 与 markdownlint 规则基本一致，但受实现限制，以下规则无法在 Python 版中校验（仍由 Prettier 统一保证）：

• MD049（斜体统一为 _）—— PyMarkdown 未实现该规则。
• MD050（加粗统一为 **）—— PyMarkdown 未实现该规则。

此外 PyMarkdown 不读取 .markdownlintignore，需在命令中显式指定扫描路径来排除 node_modules 等目录；VitePress frontmatter 需由 .pymarkdown.yaml 中的 front-matter 扩展识别（已默认开启）。

12.3 本地格式化与检查

推荐先格式化、再校验：

# 1. Prettier 格式化（自动修正排版）
bun run format

# 2. markdownlint 校验（检查语义规则）
bun run lint:md

编辑器建议安装 Prettier 与 markdownlint 插件（如 VS Code 的 esbenp.prettier-vscode 与 DavidAnson.vscode-markdownlint），二者会分别读取 .prettierrc 与 .markdownlint.jsonc 实时生效。