跳到主要内容

最佳实践

本章介绍 Markdown 编写的最佳实践，帮助你写出规范、易读、易维护的文档。

文档结构​

标题层级​

遵循合理的标题层级结构：

# 文档标题（一级标题，每篇文档仅一个）

## 章节（二级标题）

### 小节（三级标题）

#### 细节（四级标题，尽量少用）

原则：

  • 每篇文档只有一个一级标题
  • 标题层级连续，不跳级
  • 标题简洁明了，具有描述性

文档模板​

推荐的项目文档结构：

# 项目名称

简短的项目描述。

## 功能特性

- 特性一
- 特性二

## 快速开始

### 环境要求

### 安装步骤

## 使用说明

## 配置选项

## 常见问题

## 贡献指南

## 许可证

段落与换行​

段落分隔​

段落之间使用空行分隔：

这是第一段内容。

这是第二段内容。

避免手动换行​

除非必要，避免在段落内手动换行：

不推荐：
这是一段很长的文字，
手动换行会影响阅读体验。

推荐：
这是一段很长的文字，让编辑器自动换行，阅读体验更好。

句子之间使用一个空格​

中文句子之间不需要额外空格，中英文混排时适当添加空格：

推荐：使用 Markdown 编写文档非常方便。
推荐：使用 Markdown 编写 document 非常方便。

链接规范​

描述性链接文字​

链接文字应该描述目标内容：

不推荐：点击这里查看文档。
推荐：查看 [Markdown 官方文档](https://commonmark.org) 了解更多。

不推荐：详见 https://example.com/docs/guide.html
推荐：详见 [使用指南](https://example.com/docs/guide.html)

链接管理​

对于长文档或多次引用的链接，使用引用式链接：

本文参考了 [CommonMark 规范][cm] 和 [GFM 规范][gfm]。

[cm]: https://commonmark.org
[gfm]: https://github.github.com/gfm

相对路径优先​

项目内部链接使用相对路径：

推荐：[安装指南](./docs/installation.md)
不推荐：[安装指南](https://github.com/user/repo/blob/main/docs/installation.md)

图片规范​

添加替代文字​

所有图片都应添加替代文字：

推荐：![系统架构图](architecture.png)
不推荐：![](architecture.png)

图片存储位置​

将图片存放在专门的目录：

project/
├── README.md
├── docs/
│   ├── guide.md
│   └── images/
│       ├── screenshot.png
│       └── diagram.png

图片尺寸​

控制图片尺寸，避免过大：

  • 截图宽度不超过 800px
  • 使用压缩后的图片格式（PNG、WebP）
  • 必要时使用 HTML 指定尺寸

代码规范​

选择正确的语言标识​

推荐：
```python
def hello():
    print("Hello")

不推荐：

def hello():
    print("Hello")

### 代码简洁

示例代码应该简洁明了：

```markdown
推荐：
```python
# 计算两数之和
def add(a, b):
    return a + b

不推荐：

# 这是一个用于计算两个数字之和的函数
# 参数 a: 第一个数字
# 参数 b: 第二个数字
# 返回值: 两个数字的和
def add(a, b):
    """计算两个数字的和"""
    result = a + b  # 执行加法运算
    return result   # 返回结果

### 添加必要注释

代码注释应该解释"为什么"而非"是什么"：

```markdown
推荐：
```python
# 使用二分查找提高搜索效率
def binary_search(arr, target):
    ...

不推荐：

# 定义一个函数
def binary_search(arr, target):
    ...

## 列表规范

### 统一列表符号

同一文档中使用统一的列表符号：

```markdown
推荐（统一使用减号）：
- 项目一
- 项目二
- 项目三

不推荐（混用符号）：
- 项目一
* 项目二
+ 项目三

列表项一致性​

列表项的格式应保持一致：

推荐：
- 安装依赖
- 配置环境
- 运行项目

不推荐：
- 首先安装依赖
- 然后配置环境
- 运行项目

嵌套层级​

嵌套层级不宜过深，建议不超过三级：

推荐：
- 主项
  - 子项
    - 孙项（到此为止）

不推荐：
- 主项
  - 子项
    - 孙项
      - 曾孙项
        - 玄孙项

表格规范​

保持简洁​

表格列数不宜过多：

推荐（3-4列）：
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| name | string | 名称 |

不推荐（过多列）：
| 参数 | 类型 | 说明 | 默认值 | 是否必填 | 版本 | 示例 |

对齐方式​

根据内容选择合适的对齐方式：

| 参数 | 数量 | 状态 |
| :--- | ---: | :---: |
| 名称（左对齐） | 100（右对齐） | 正常（居中） |

表头必填​

表格应有表头：

推荐：
| 名称 | 值 |
| --- | --- |
| 参数 | 值 |

不推荐：
| 参数 | 值 |
| --- | --- |
| 参数 | 值 |

格式一致性​

空行规则​

  • 标题前后空一行
  • 列表前后空一行
  • 代码块前后空一行
  • 表格前后空一行
标题前的空行

## 标题

标题后的空行

段落内容。

- 列表项一
- 列表项二

列表后的空行

```代码块```

代码块后的空行

标点符号​

中文文档使用中文标点：

推荐：这是中文文档，使用中文标点。
不推荐：这是中文文档,使用英文标点.

可读性优化​

适当分段​

长段落应适当分段，每段 3-5 句为宜。

使用小标题​

长文档使用小标题划分内容：

## 安装

### 系统要求

### 安装步骤

### 验证安装

突出重点​

使用粗体、斜体突出重点：

**重要**：请确保已备份数据。

注意：此操作*不可撤销*。

版本控制友好​

纯文本格式​

Markdown 是纯文本格式，适合版本控制：

  • 每行不宜过长（建议 80-120 字符）
  • 避免二进制文件频繁变更
  • 图片使用外部引用

提交信息​

Markdown 文件的提交信息应清晰：

docs: 更新安装指南

- 添加 Windows 安装说明
- 更新依赖版本要求
- 修复链接错误

常见错误​

语法错误​

错误：#没有空格
正确：# 有空格

错误：** 粗体 **
正确：**粗体**

错误：[链接] (地址)
正确：[链接](地址)

格式混乱​

错误：
# 标题
段落
## 标题

正确：

# 标题

段落

## 标题

过度格式化​

错误：这是***超级重要***的内容
正确：这是**重要**的内容

小结​

本章学习了 Markdown 编写的最佳实践：

  1. 文档结构：合理的标题层级和文档模板
  2. 链接规范：描述性文字、引用式链接
  3. 图片规范：替代文字、统一存储
  4. 代码规范：语言标识、简洁示例
  5. 格式一致性：空行、标点、符号统一
  6. 可读性：分段、小标题、突出重点

练习​

  1. 按照文档模板创建一个项目 README
  2. 重构一篇格式混乱的文档
  3. 使用引用式链接管理文档中的所有链接
  4. 创建一个规范的项目文档