文档排版时列点总乱？Markdown有序列表无序列表写法教程含代码示例和排版技巧

最近帮几个朋友改文档，发现大家用Markdown写列表的时候，经常会遇到一些让人头疼的问题。比如列表缩进突然错乱、序号对不齐、嵌套的时候样式乱了，甚至有时候明明没写复杂，渲染出来却像是一团乱麻。其实列表看着简单，真正用起来还是有不少门道在里面的。

今天就把有序列表和无序列表的写法，连带一些实用技巧，一起掰开揉碎了讲清楚。

---

列表的两种基本形态

Markdown里最常见的列表分两种：用符号的，叫无序列表；用数字的，叫有序列表。

无序列表长这样，用-、*或者+开头就行：

- 苹果
- 香蕉
- 橙子

渲染出来就是：

• 苹果
• 香蕉
• 橙子

三种符号效果是一样的，选一个习惯用的就好。*和+在大多数编辑器里效果相同，但有些小众渲染器对*和+的处理可能有细微差异，所以建议统一用-，最稳妥。

有序列表用数字加个点：

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

渲染出来：

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

这里有个小知识点：Markdown引擎会自动根据你的数字推断序号，也就是说，你写的数字其实不重要，引擎会按顺序重新编号。所以下面这样写：

1. 第一个
5. 第二个
3. 第三个

渲染后仍然是 1、2、3。不过如果你的意图是表示”跳过了某些项”，这种写法反而是有用的，比如步骤说明中刻意留空：

1. 安装基础环境
2. 配置网络参数
   （此处省略中间配置步骤...）
8. 启动服务验证

渲染后会自动变成 1、2、3，看起来有点迷惑。如果确实需要显示”跳步”效果，推荐改用无序列表，或者直接在文字里写清楚。

---

嵌套列表，最容易出问题的地方

很多人写列表不嵌套，一切正常；一旦加了一层缩进，问题就来了。

无序列表嵌套无序列表

- 前端开发
  - HTML
    - 标签基础
    - 语义化标签
  - CSS
    - 选择器
    - 布局方案
  - JavaScript
    - 基础语法
    - 框架
- 后端开发
  - Node.js
  - Python
  - Go

渲染效果：

• 前端开发
  • HTML
    • 标签基础
    • 语义化标签
  • CSS
    • 选择器
    • 布局方案
  • JavaScript
    • 基础语法
    • 框架
• 后端开发
  • Node.js
  • Python
  • Go

关键点在于：缩进必须用空格，不能用Tab。不同编辑器和渲染器对Tab的处理不一样，有的会被截断，有的会变成4个空格，导致渲染结果不一致。

最稳妥的写法是每个层级用4个空格缩进：

- 第一层
    - 第二层
        - 第三层
            - 第四层

有序列表嵌套无序列表

1. 准备工作
   - 下载源码
   - 安装依赖
   - 配置环境变量
2. 开始部署
   - 创建数据库
   - 导入数据
   - 启动服务

渲染效果：

1. 准备工作
   • 下载源码
   • 安装依赖
   • 配置环境变量
2. 开始部署
   • 创建数据库
   • 导入数据
   • 启动服务

这种混排很常见，比如写教程或者说明文档，步骤下面列出子项。嵌套的层级前面同样用4个空格缩进。

有序列表嵌套有序列表

1. 前期调研
   1. 收集竞品信息
   2. 分析用户痛点
   3. 确定产品方向
2. 中期开发
   1. 搭建技术架构
   2. 实现核心功能
   3. 编写单元测试
3. 后期测试
   1. 集成测试
   2. 性能测试
   3. 安全测试

渲染效果：

1. 前期调研
   1. 收集竞品信息
   2. 分析用户痛点
   3. 确定产品方向
2. 中期开发
   1. 搭建技术架构
   2. 实现核心功能
   3. 编写单元测试
3. 后期测试
   1. 集成测试
   2. 性能测试
   3. 安全测试

注意：嵌套有序列表时，子项的序号也要从1开始写，虽然引擎会自动处理，但这样写更清晰，阅读源码的时候不容易搞混。

---

几个容易踩的坑

坑一：列表和段落混排时出现意外间距

有时候你在列表中间插入一段文字，渲染出来间距会变大：

- 项目开始
  这是一个重要说明，解释了为什么我们要做这个项目。

- 项目执行
  按计划推进即可。

渲染效果会出问题，中间那段文字可能被识别成了列表项的内容，导致样式不对。

正确写法：如果列表中间要插一段正文，用HTML的<p>标签或者直接加一个空行再写普通段落，但要注意空行的位置：

- 项目开始

这是一个重要说明，解释了为什么我们要做这个项目。

- 项目执行
  按计划推进即可。

或者更安全的做法是，把段落写在列表项内部，用缩进包裹：

- 项目开始
  这是一个重要说明，解释了为什么我们要做这个项目。

- 项目执行
  按计划推进即可。

这里的差别很微妙，多几个空格或者少几个空格效果都不一样，建议多测试几次。

坑二：列表项里的代码块

在列表里放代码块，缩进要再加一级：

1. 安装依赖
   执行以下命令：

   ```bash
   npm install

1. 启动服务 执行：

   npm start

这里代码块前面用了**3个缩进层级**（1个列表级 + 2个代码块级），总共8个空格，或者用Tab加空格组合。不过最稳妥的是直接用4个空格缩进：

```markdown
1. 安装依赖
   执行以下命令：

    ```bash
    npm install
    ```

2. 启动服务
   执行：

    ```bash
    npm start
    ```

渲染效果：

1. 安装依赖 执行以下命令：

   npm install

1. 启动服务 执行：

   npm start

坑三：列表后面直接跟标题

- 这是列表项

## 这是一个标题

渲染之后标题和列表之间可能会有额外的间距，这是因为Markdown解析器把标题前面的空行当成了段落分隔。解决方法是在标题前面加一个空行，或者用HTML注释隔断：

- 这是列表项

<!-- -->

## 这是一个标题

---

一些进阶小技巧

用列表做待办事项

Markdown本身没有原生的待办事项语法，但大多数平台（GitHub、GitLab、飞书、语雀等）都支持：

- [ ] 完成需求文档
- [ ] 设计交互原型
- [x] 搭建开发环境
- [x] 配置CI/CD流程

渲染出来就是带复选框的列表，已经勾选的会自动删除线显示。这个功能在做任务清单和进度跟踪的时候非常实用。

列表里加链接和强调

- 详细文档请查看 [官方API文档](https://example.com/docs)
- 如果遇到**报错**，请先检查：
  - 环境变量是否正确设置
  - 端口是否被占用
  - 依赖版本是否一致

渲染效果：

• 详细文档请查看 官方API文档
• 如果遇到报错，请先检查：
  • 环境变量是否正确设置
  • 端口是否被占用
  • 依赖版本是否一致

列表里完全可以正常使用Markdown的所有语法，链接、加粗、斜体、代码引用都可以。

超长列表的视觉优化

如果你有一段很长的列表，比如列出20个知识点，渲染出来密密麻麻的，可以考虑用有序列表分段，或者在中间插入分隔线：

1. HTML基础
2. CSS基础
3. JavaScript基础
4. Git版本控制

---

5. React基础
6. Vue基础
7. Node.js基础
8. 数据库入门

分隔线把长列表自然分成了两段，阅读体验好很多。

---

快速对照表

场景	推荐写法
简单列举	无序列表，用-
有顺序的步骤	有序列表，数字从1开始
列表中间要插段落	列表项内缩进文字，或用HTML隔断
列表里放代码块	缩进再加一级（8空格）
任务清单	- [ ]和- [x]
混排有序+无序	注意缩进层级，每层4空格

---

列表看着是Markdown里最简单的语法，但真要写好、写规范，细节还是不少的。掌握这些技巧和坑点之后，写出来的文档排版会整齐很多，读的人也舒服。下次写文档的时候，不妨多试几次嵌套和混排的写法，找到最适合自己的节奏。