本文档基于 markdownlint 规则，定义项目中 Markdown 文件的编写规范。

目录

标题规范

MD001 - 标题层级递增

标题层级应该递增，不能跳级。

❌ 错误示例：

# 一级标题
### 三级标题（跳过了二级标题）

✅ 正确示例：

# 一级标题
## 二级标题
### 三级标题

MD003 - 标题风格统一

统一使用 ATX 风格标题（#），不使用 Setext 风格。

❌ 错误示例：

标题一
======

标题二
------

✅ 正确示例：

# 标题一

## 标题二

MD018 - 标题符号后需要空格

# 后面必须有一个空格。

❌ 错误示例：

#标题
##标题

✅ 正确示例：

# 标题
## 标题

MD019 - 标题符号后只能有一个空格

# 后面只能有一个空格。

❌ 错误示例：

#  标题（两个空格）

✅ 正确示例：

# 标题

MD022 - 标题前后需要空行

标题前后应该有空行（文件开头除外）。

❌ 错误示例：

一些文本
## 标题
接下来的内容

✅ 正确示例：

一些文本

## 标题

接下来的内容

MD023 - 标题不能缩进

标题不应该有缩进。

❌ 错误示例：

Some text

  # 标题

✅ 正确示例：

Some text

# 标题

MD024 - 避免重复标题

同一文档中不应该有内容完全相同的标题（同级标题）。

❌ 错误示例：

## 功能介绍
一些内容

## 功能介绍（重复）

✅ 正确示例：

## 功能介绍
一些内容

## 高级功能介绍

MD025 - 只能有一个一级标题

文档中只能有一个一级标题（#）。

❌ 错误示例：

# 标题一
# 标题二

✅ 正确示例：

# 主标题
## 章节一
## 章节二

MD041 - 文件应以一级标题开始

Markdown 文件的第一行应该是一级标题。

❌ 错误示例：

这是一段介绍文字

# 标题

✅ 正确示例：

# 标题

这是一段介绍文字

列表规范

MD004 - 无序列表符号统一

无序列表应使用统一的符号，推荐使用 -。

❌ 错误示例：

- 项目一
* 项目二
+ 项目三

✅ 正确示例：

- 项目一
- 项目二
- 项目三

MD005 - 同级列表项缩进一致

同级列表项的缩进应该保持一致。

❌ 错误示例：

- 项目一
  - 子项目一
   - 子项目二（缩进不一致）

✅ 正确示例：

- 项目一
  - 子项目一
  - 子项目二

MD006 - 列表项不要从行首开始缩进

顶级列表项不应该有缩进。

❌ 错误示例：

- 项目一
- 项目二

✅ 正确示例：

- 项目一
- 项目二

MD007 - 无序列表缩进使用2个空格

无序列表的子项目缩进应该使用 2 个空格。

❌ 错误示例：

- 项目一
    - 子项目（4个空格）

✅ 正确示例：

- 项目一
  - 子项目（2个空格）

MD029 - 有序列表序号

有序列表建议使用递增序号，或全部使用 1.

✅ 推荐示例（递增序号）：

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

✅ 可选示例（全部使用1）：

1. 第一项
1. 第二项
1. 第三项

MD030 - 列表符号后需要空格

列表符号（-、*、+、数字.）后必须有空格。

❌ 错误示例：

-项目一
1.项目一

✅ 正确示例：

- 项目一
1. 项目一

MD032 - 列表前后需要空行

列表前后应该有空行（文件开头和列表嵌套除外）。

❌ 错误示例：

一些文本
- 项目一
- 项目二
接下来的文本

✅ 正确示例：

一些文本

- 项目一
- 项目二

接下来的文本

代码块规范

MD031 - 代码块前后需要空行

围栏式代码块前后应该有空行。

❌ 错误示例：

一些文本
```code
code here
```
接下来的文本

✅ 正确示例：

一些文本

```code
code here
```

接下来的文本

MD040 - 代码块应指定语言

围栏式代码块应该指定语言类型。

❌ 错误示例：

```
const a = 1;
```

✅ 正确示例：

```javascript
const a = 1;
```

MD046 - 代码块风格统一

统一使用围栏式代码块（```），不使用缩进式代码块。

❌ 错误示例：

Some text.

    const a = 1;  // 缩进式代码块

More text.

```javascript
const a = 1;
```

More text.

✅ 正确示例：

Some text.

```javascript
const a = 1;
```

More text.

```javascript
const b = 2;
```

MD049 - 行内代码使用反引号

行内代码应该使用反引号（`）包裹。

✅ 正确示例：

使用 `console.log()` 输出信息。

链接和图片规范

MD034 - URL应使用尖括号或链接格式

裸露的 URL 应该使用尖括号包裹或使用链接格式。

❌ 错误示例：

https://example.com

✅ 正确示例：

<https://example.com>
[示例网站](https://example.com)

MD039 - 链接文本两侧不应有空格

链接文本的方括号内两侧不应该有空格。

❌ 错误示例：

[ 链接文本 ](https://example.com)

✅ 正确示例：

[链接文本](https://example.com)

MD042 - 链接URL不能为空

链接必须有有效的 URL。

❌ 错误示例：

[链接]()

✅ 正确示例：

[链接](https://example.com)

MD045 - 图片应有alt文本

图片应该有 alt 文本描述。

❌ 错误示例：

![](image.png)

✅ 正确示例：

![图片描述](image.png)

段落和换行

MD009 - 行尾不应有多余空格

行尾不应该有多余的空格（除非是用于换行的两个空格）。

❌ 错误示例：

这是一行文本

✅ 正确示例：

这是一行文本

MD010 - 不使用硬制表符（Tab）

使用空格代替 Tab 缩进。

❌ 错误示例：使用 Tab 缩进

✅ 正确示例：使用空格缩进

MD012 - 不应有连续多个空行

不应该有连续的多个空行。

❌ 错误示例：

段落一



段落二（多个空行）

✅ 正确示例：

段落一

段落二

MD047 - 文件应以空行结尾

Markdown 文件应该以一个空行结束。

✅ 正确示例：文件最后有一个空行

强调和格式

MD036 - 不要用强调代替标题

不应该用加粗或斜体来代替标题。

❌ 错误示例：

**这是一个章节**

✅ 正确示例：

## 这是一个章节

MD037 - 强调标记内侧不应有空格

强调标记（* 或 _）内侧不应该有空格。

❌ 错误示例：

** 加粗文本 **
* 斜体文本 *

✅ 正确示例：

**加粗文本**
*斜体文本*

MD049/MD050 - 强调风格统一

强调符号应该统一使用：

  • 斜体：使用 *斜体*
  • 加粗：使用 **加粗**

✅ 推荐示例：

*斜体文本*
**加粗文本**
***加粗斜体***

其他规范

MD013 - 行长度限制（可选）

建议每行不超过 80-120 字符（中文可适当放宽）。

配置建议：根据项目需求调整或禁用此规则。

MD014 - Shell命令前不要加美元符号

Shell 命令示例中不应该包含 $ 提示符。

❌ 错误示例：

$ npm install
$ npm start

✅ 正确示例：

npm install
npm start

MD026 - 标题末尾不要有标点符号

标题末尾不应该有 .、,、;、: 等标点符号（? 和 ! 允许）。

❌ 错误示例：

## 项目介绍。

✅ 正确示例：

## 项目介绍
## 这是什么？（允许问号）

MD033 - 不使用HTML标签（可选）

尽量避免在 Markdown 中使用 HTML 标签，除非必要。

❌ 不推荐：

<h1>标题</h1>
<b>加粗</b>

✅ 推荐：

# 标题
**加粗**

MD038 - 行内代码两侧不应有空格

行内代码的反引号内侧不应该有空格。

❌ 错误示例：

` code `

✅ 正确示例：

`code`

MD002 - 第一个标题应该是一级标题（已弃用）

此规则已被 MD041 替代。

MD011 - 链接语法错误

链接语法应该正确，方括号和圆括号要匹配。

❌ 错误示例：

[链接文本](https://example.com
[链接文本https://example.com)

✅ 正确示例：

[链接文本](https://example.com)

MD020 - 闭合的 ATX 标题内侧需要空格

使用闭合的 ATX 标题时，# 内侧需要空格。

❌ 错误示例：

#标题#
##标题##

✅ 正确示例：

# 标题 #
## 标题 ##

MD021 - 闭合的 ATX 标题外侧需要空格

使用闭合的 ATX 标题时，外侧 # 也需要空格。

❌ 错误示例：

# 标题#
## 标题##

✅ 正确示例：

# 标题 #
## 标题 ##

MD027 - 引用块后需要空格

引用符号 > 后面需要空格。

❌ 错误示例：

>引用内容
>>嵌套引用

✅ 正确示例：

> 引用内容
> > 嵌套引用

MD028 - 引用块内不应有空行

引用块内部不应该有连续的空引用行。

❌ 错误示例：

> 第一段引用
>
> 第二段引用

✅ 正确示例：

> 第一段引用
> 第二段引用

或者使用分隔的引用块：

> 第一段引用

> 第二段引用

MD035 - 分隔线风格统一

分隔线应该使用统一的风格。

❌ 错误示例：

---
***
___

✅ 正确示例（统一使用一种）：

---
---
---

MD043 - 必需的标题结构（可选）

可以定义文档必须遵循的标题结构。

配置建议：根据项目需求自定义标题结构。

MD044 - 特定单词的大小写（可选）

可以定义特定单词或短语的正确大小写。

示例：

{
  "MD044": {
    "names": ["JavaScript", "TypeScript", "GitHub"],
    "code_blocks": false
  }
}

MD048 - 代码围栏风格

代码块围栏应使用统一的风格。

❌ 混合使用：

```python
code
```

~~~python
code
~~~

✅ 统一使用：

```python
code
```

```python
code
```

MD051 - 链接片段应该有效（可选）

文档内部链接的锚点应该是有效的。

❌ 错误示例：

[跳转到不存在的章节](#不存在的锚点)

✅ 正确示例：

## 章节标题

[跳转到章节](#章节标题)

MD052 - 引用链接和图片应该有定义

使用引用式链接时，必须有对应的定义。

❌ 错误示例：

[链接文本][ref]
<!-- 缺少 [ref] 的定义 -->

✅ 正确示例：

[链接文本][ref]

[ref]: https://example.com

MD053 - 链接和图片引用定义应该被使用

定义的引用链接应该在文档中被使用。

❌ 错误示例：

[ref]: https://example.com
<!-- 定义了但未使用 -->

✅ 正确示例：

[链接文本][ref]

[ref]: https://example.com

MD054 - 链接和图片样式统一

链接和图片应使用统一的样式（内联或引用）。

❌ 混合使用：

[内联链接](https://example.com)
[引用链接][ref]

[ref]: https://example.com

✅ 统一使用：

[链接一](https://example.com)
[链接二](https://example.com)

MD055 - 表格管道符号风格统一

表格应使用统一的管道符号风格。

❌ 不一致：

| 列1 | 列2
|-----|-----
| 值1 | 值2 |

✅ 一致：

| 列1 | 列2 |
|-----|-----|
| 值1 | 值2 |

MD056 - 表格列数应一致

表格每行的列数应该一致。

❌ 错误示例：

| 列1 | 列2 | 列3 |
|-----|-----|
| 值1 | 值2 |

✅ 正确示例：

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 值1 | 值2 | 值3 |

MD058 - 表格需要标题行

表格应该有标题行。

❌ 错误示例：

|-----|-----|
| 值1 | 值2 |

✅ 正确示例：

| 列1 | 列2 |
|-----|-----|
| 值1 | 值2 |

完整规则列表

已实现规则

规则编号 说明 严重程度
MD001 标题层级递增 error
MD003 标题风格统一（ATX） error
MD004 无序列表符号统一 error
MD005 同级列表项缩进一致 error
MD006 列表项不从行首缩进 error
MD007 无序列表缩进2空格 error
MD009 行尾无多余空格 error
MD010 不使用Tab error
MD011 链接语法正确 error
MD012 无连续多空行 error
MD013 行长度限制 warning
MD014 Shell命令无$符号 error
MD018 标题#后需空格 error
MD019 标题#后只一个空格 error
MD020 闭合ATX标题内侧空格 error
MD021 闭合ATX标题外侧空格 error
MD022 标题前后空行 error
MD023 标题不缩进 error
MD024 避免重复标题 error
MD025 只一个一级标题 error
MD026 标题末尾无标点 error
MD027 引用块后空格 error
MD028 引用块内无空行 error
MD029 有序列表序号 error
MD030 列表符号后空格 error
MD031 代码块前后空行 error
MD032 列表前后空行 error
MD033 不使用HTML标签 warning
MD034 URL使用尖括号 error
MD035 分隔线风格统一 error
MD036 不用强调代替标题 error
MD037 强调标记内侧无空格 error
MD038 行内代码两侧无空格 error
MD039 链接文本两侧无空格 error
MD040 代码块指定语言 error
MD041 文件以一级标题开始 error
MD042 链接URL不为空 error
MD043 必需的标题结构 warning
MD044 特定单词大小写 warning
MD045 图片有alt文本 error
MD046 代码块风格统一 error
MD047 文件以空行结尾 error
MD048 代码围栏风格统一 error
MD049 斜体风格统一 error
MD050 加粗风格统一 error
MD051 链接片段有效 warning
MD052 引用有定义 error
MD053 定义被使用 error
MD054 链接样式统一 warning
MD055 表格管道符统一 error
MD056 表格列数一致 error
MD058 表格有标题行 error

未包含规则

以下规则编号在 markdownlint 中未定义或已弃用：

  • MD002（已被 MD041 替代）
  • MD008（已合并到 MD009）
  • MD015-MD017（未定义）
  • MD057（未定义）
  • MD059-MD060（未定义）

常用规则速查表

规则编号 说明 示例
MD001 标题层级递增 # h1 → ## h2
MD003 标题风格统一 使用 # 而不是下划线
MD004 无序列表符号统一 统一使用 -
MD007 列表缩进2空格 - item
- subitem
MD009 行尾无多余空格 删除行尾空格
MD012 无连续多空行 最多一个空行
MD022 标题前后空行 标题前后需要空行
MD025 只能有一个一级标题 全文只有一个 # h1
MD031 代码块前后空行 代码块前后需要空行
MD032 列表前后空行 列表前后需要空行
MD040 代码块指定语言 markdown ```python
MD047 文件结尾空行 文件最后一行为空行
MD055 表格管道符统一 每行开始和结束都有 `
MD056 表格列数一致 所有行列数相同

规则优先级建议

必须遵守（error）

以下规则影响文档可读性和规范性，必须遵守：

  • 标题类：MD001, MD003, MD018, MD019, MD022, MD023, MD025, MD041
  • 列表类：MD004, MD005, MD006, MD007, MD030, MD032
  • 代码类：MD031, MD040, MD046, MD047
  • 链接类：MD011, MD034, MD039, MD042, MD045
  • 格式类：MD009, MD010, MD012

建议遵守（warning）

以下规则可根据项目需求调整：

  • MD013（行长度，中文文档可放宽）
  • MD033（HTML标签，复杂格式时允许）
  • MD043（标题结构，适用于固定模板）
  • MD044（单词大小写，品牌词汇）

团队协商

以下规则可由团队协商决定：

  • MD029（有序列表序号风格）
  • MD035（分隔线风格）
  • MD048（代码围栏风格）
  • MD054（链接样式）

最后更新时间：2025-11-16
基于版本：markdownlint v0.39.0