正文

手把手教你用Markdown快速创建有序无序列表 含代码示例及常见排版错误排查

/0 浏览量
0901

Hey，先把那些复杂的 HTML 标签扔进回收站吧！我知道你讨厌在 <ul>、<li> 和 <ol> 之间反复横跳，还要担心缩进对不对，搞得头发都掉了一把。Markdown 的出现就是来救命的，尤其是处理列表时，它简单得就像你平时做的购物清单一样自然。

今天咱们不整那些虚头巴脑的理论，直接上手。我会把有序列表和无序列表的写法掰开了揉碎了讲，顺便把那些让你抓狂的“为什么我的列表变乱了”的坑给你填平。读完这篇，你再也不用因为排版错乱而怀疑人生了。

一、 无序列表：最随意的表达

无序列表就是那种没有顺序之分的条目堆叠，通常用来列举并列的观点、功能点或者素材。在 Markdown 里，它有两种主流写法：短横线 -、加号 + 和星号 *。

1.1 基础写法：随便选一个符号

其实这三者在绝大多数渲染器（比如 GitHub、Typora、VS Code）里效果是一模一样的。但我个人强烈推荐用短横线 -，因为它最不容易和数学公式或者其他符号混淆，打字顺手。

- 苹果
- 香蕉
- 橙子

渲染出来就是：

  • 苹果
  • 香蕉
  • 橙子

1.2 嵌套层级：缩进是关键

这是新手最容易栽跟头的地方。你想让“草莓”和“蓝莓”成为“水果”的子项，该怎么办？靠缩进！

注意看，子项前面必须有空格。通常一个层级用 2 个或 4 个空格（我习惯用 2 个，看着清爽；但为了兼容性，很多教程建议用 4 个）。

- 食品
  - 水果
    - 苹果
    - 香蕉
  - 蔬菜
    - 菠菜
    - 白菜
- 饮料
  - 可乐
  - 奶茶

这里有个隐藏的大坑：很多人会问，“我用 Tab 键缩进行不行？”

绝对不行！ 除非你的编辑器把 Tab 设置了成 2 或 4 个空格。否则，Tab 键在某些渲染器里会被当成代码块或者产生难以捉摸的空格，导致列表层级错乱。请务必使用空格键。

二、 有序列表：当顺序很重要时

如果这事儿有先后顺序，比如步骤、排名、优先级，那就得上有序列表了。用数字加点 1.、2. 这种格式。

2.1 自动编号的智慧

Markdown 的有序列表有个很有意思的特性：你填什么数字，它不一定就显示什么数字。 大多数渲染器会自动根据前面的数字顺延。

1. 第一步：打开电脑
2. 第二步：启动编辑器
3. 第三步：开始编写

你看，我写的是 1, 2, 3，渲染出来也是 1, 2, 3。

但是，如果你写成这样：

1. 准备工作
3. 开始执行
2. 检查收尾

渲染出来的结果依然是 1. 准备工作, 2. 开始执行, 3. 检查收尾。渲染器会忽略你写的具体数字，只认它是有序列表。

专家建议：为了代码的可读性和便于团队协作，永远从 1. 开始，并且保持顺序递增。虽然渲染器会帮你纠正，但如果你写乱了，其他看源码的人会懵圈。

2.2 混合使用：无序套有序，或者有序套无序

实际写文档时，这两种列表经常嵌套。

1. 准备食材
   - 鸡蛋 2 个
   - 盐 少许
   - 葱花 一把
2. 开始烹饪
   - 打散鸡蛋
   - 热油翻炒
3. 装盘享用

2.3 特殊场景：字母或罗马数字列表

标准的 Markdown 语法不支持直接生成 a. b. c. 或 i. ii. iii. 的有序列表。如果你需要这种格式，有两个办法：

  1. 硬写 HTML：直接在 Markdown 里嵌入 HTML 标签（不推荐，破坏 Markdown 简洁性）。
  2. 利用扩展语法：如果你用的是 Typora 或者配置了特定插件（如 Pandoc）的编辑器，有些支持自定义列表风格，但这属于高级玩法，日常写文档没必要折腾这个。

三、 常见排版错误排查（避坑指南）

这部分是精华。很多人 Markdown 写得溜，但列表就是断断续续，90% 是因为下面这几个坑。

3.1 错误一：列表项与文字混排，且没有空行

这是最经典的错误。你想在列表中间加一句解释性的话，结果一换行，列表就断了。

错误示范：

- 第一点内容
这是补充说明。
- 第二点内容

结果： “这是补充说明”会被当成普通段落，而不是第一点的子内容，而且列表会在这里中断，重新从头开始或者变成无序列表。

正确做法： 如果要在列表项里插入多行文本，每行都要缩进。

- 第一点内容
  这是补充说明，属于第一点的一部分。
  这是第二行补充说明。
- 第二点内容

技巧：如果你在 VS Code 里，选中文字直接按 Tab 键可以批量缩进，但记得检查是不是变成了空格。

3.2 错误二：符号后面必须有空格

这是语法强制要求。

-苹果
*香蕉
1.橙子

结果： 大部分渲染器会报错，或者把它们当成普通文本，不会显示成列表样式。

必须这样写：

- 苹果
* 香蕉
1. 橙子

注意：符号和文字之间必须至少有一个空格。

3.3 错误三：列表前后没有空行（边界不清）

有时候你列表前面紧挨着代码块或者标题，渲染器会懵。

错误示范：

```python
print("hello")
  • 列表项A
  • 列表项B

有些老旧的渲染器会把列表项 A 吃进代码块里，或者导致列表样式丢失。

**正确做法：** 列表前后最好都留一个空行。

```markdown
```python
print("hello")
  • 列表项A
  • 列表项B

### 3.4 错误四：链接、图片打断列表

这是高阶玩家的痛点。你想在列表里放一个图片，结果图片一出现，列表断了。

```markdown
1. 先做这个
   ![图片](http://example.com/img.jpg)
2. 再做那个

现象： 第 2 点可能丢失，或者图片前后的缩进乱了。

解决方法： 确保图片行也有正确的缩进（通常是 3 或 4 个空格，取决于外层列表的缩进层级）。

1. 先做这个
   ![图片](http://example.com/img.jpg)
2. 再做那个

仔细看：图片前面的缩进要比 1. 多一级。如果 1. 后面有 2 个空格，图片前面至少要有 3 个空格（通常为了保险，直接再缩进 2 个空格，即总共 4 个空格）。

四、 终极检查清单：如何一眼看出列表写错了？

作为专家，我教你几个快速自查的技巧，不用肉眼一个个数：

  1. 开启“显示空白字符”：在 VS Code 或 Typora 中，开启显示不可见字符（通常是那个 符号）。
    • 检查列表项前面的 - 或 1. 后面是不是真的有空格。
    • 检查缩进是不是全是空格，没有混入 Tab。
  2. 预览模式观察层级线：
    • 在 Typora 等支持可视化缩进线的编辑器里，如果层级线断了，说明缩进层级错了。
    • 如果本该是子项的内容突然顶格了，那就是缩进少了。
  3. 复制粘贴测试：
    • 把怀疑有问题的列表复制到一个在线 Markdown 编辑器（如 Dillinger.io）里，看渲染结果。不同编辑器的容错率不同，能帮你定位是不是语法问题。

五、 代码示例：一个完整的复杂列表

为了让你更有感觉，我们写一个带代码块、图片、链接的复杂嵌套列表，这是真实项目文档中常见的场景。

## 环境配置步骤

1. **安装 Node.js**
   - 访问官网 [nodejs.org](https://nodejs.org) 下载 LTS 版本。
   - ![安装界面](https://nodejs.org/images/logo.png)
   - 运行安装程序，一路“下一步”即可。

2. **初始化项目**
   - 打开终端（Terminal）。
   - 执行以下命令创建项目：
     ```bash
     npm init -y
     ```
   - 看到 `package.json` 生成，说明成功。

3. **安装依赖**
   - 安装 Express：
     ```bash
     npm install express
     ```
   - 安装开发依赖（可选）：
     - ESLint（代码规范）
     - Prettier（代码格式化）
     - Jest（单元测试）

4. **启动服务**
   - 编写 `index.js`：
     ```javascript
     const express = require('express');
     const app = express();
     app.get('/', (req, res) => res.send('Hello World'));
     app.listen(3000);
     ```
   - 运行 `node index.js`，浏览器访问 `http://localhost:3000`。

解析这个例子：

  • 第 1 点里嵌套了链接和图片，图片有 3 个空格缩进（相对于 1. 的 1 个数字+1 个点+1 个空格，再加 2 个空格缩进）。
  • 第 2 点里嵌入了代码块，代码块需要 4 个空格缩进（因为它在列表项内，比列表缩进再深一层）。
  • 第 3 点里又套了无序列表，用了短横线 -。
  • 第 4 点里既有代码块又有普通文本。

如果你能理解并写出上面这个结构，那 Markdown 列表这一关，你就彻底通关了。

六、 给小朋友的比喻：整理玩具箱

如果你身边有个小朋友，或者你想用最直观的方式记住，可以这么想：

  • 无序列表就像你把玩具倒在地板上，没有顺序，随便堆一堆：积木、小熊、汽车。用 - 代表每个玩具是一个独立的小圆圈。
  • 有序列表就像你要按步骤搭积木：第一步拿底座，第二步搭墙，第三步封顶。必须按顺序来，不然房子会塌。
  • 嵌套就像把小熊放进盒子里，再把盒子放进抽屉里。每深入一层，就要往右挪一点（缩进），这样你才知道哪个玩具属于哪个盒子。
  • 空格就是玩具和玩具之间的间隔，没间隔它们会挤在一起，分不清谁是谁。

好了，今天的内容就到这里。记住，Markdown 列表的核心就三个字：符号、空格、缩进。把这三样搞明白了，99% 的列表问题都能迎刃而解。下次再遇到列表错乱，别慌，先打开你的编辑器，看看是不是哪里少了个空格，或者缩进没对齐。

祝你写得开心，排版永远整齐！

-- 展开阅读全文 --