正文

用代码实例讲透Markdown无序有序列表嵌套写法及常见格式错误避坑指南

/0 浏览量
0910

嘿，朋友。我是 Agnes。今天咱们不聊虚的，专门来“解剖”一下 Markdown 里最基础、却也是最容易让人抓狂的列表嵌套问题。

你有没有过这种经历：在编辑器里看着挺顺眼，一预览，列表全乱了？或者在 GitHub 上看着整齐，发到博客里缩进全没了？甚至更惨，写了几十层的嵌套，结果层级彻底崩坏，像个烂尾楼。

别急，今天我就用最直白的大白话，配合最硬核的代码实例，把无序列表、有序列表、以及它们俩“混血”嵌套的底层逻辑给你讲透。同时，我会把你容易踩的坑——那些坑我当初也踩过，血泪教训啊——一个个给你填平。

先聊聊“灵魂三问”：什么是嵌套？为什么要嵌套？

在敲代码之前，咱得先建立个直觉。

嵌套是什么？ 想象一下俄罗斯套娃。最外面是大娃娃（一级列表），里面套着小娃娃（二级列表），小娃娃里面还可能套着更小的（三级列表）。在 Markdown 里，这就是“缩进”。每一层缩进，就意味着你的内容“隶属于”上一层的那个点。

为什么要嵌套？ 因为世界是层次结构的。

  • 你做菜谱：主料 -> 辅料 -> 具体用量。
  • 你写技术文档：安装步骤 -> 命令示例 -> 参数说明。
  • 你列计划：本周目标 -> 具体任务 -> 截止时间。

如果不嵌套，所有内容都平铺直叙，读起来会累死。嵌套，就是给读者指路，告诉他们：“嘿，这条是上一条的详细说明。”

第一关：无序列表的嵌套（-, *, +）

无序列表用的是 -、* 或 +。在嵌套时，核心规则只有一个：缩进。

1.1 标准嵌套写法（最稳妥）

通常，每一级缩进 2 个空格 或 4 个空格 是最通用的。虽然不同的渲染器（比如 GitHub、Typora、VS Code）可能略有差异，但 4 个空格 是公认的“黄金标准”。

## 我的购物清单

- 生鲜食品
  - 水果
    - 苹果（红富士）
    - 香蕉
  - 蔬菜
    - 菠菜
    - 西兰花
- 日用品
  - 洗发水
  - 牙膏

预览效果（脑补一下）：

- 生鲜食品
  - 水果
    - 苹果（红富士）
    - 香蕉
  - 蔬菜
    - 菠菜
    - 西兰花
- 日用品
  - 洗发水
  - 牙膏

关键点解析：

  • 第一层“生鲜食品”顶格写。
  • 第二层“水果”前面有 4 个空格（或者 2 个，取决于你的编辑器设置，但建议保持一致）。
  • 第三层“苹果”前面有 8 个空格。

Agnes 的小贴士： 如果你的编辑器开启了“显示空白字符”，你会看到那些空格。如果没有，千万别乱敲 Tab 键！Tab 键在某些 Markdown 解析器里会被转换成 4 个或 8 个空格，但在另一些地方可能只算 1 个，导致缩进对齐全乱。用空格，别用 Tab。

1.2 混用符号的嵌套（进阶技巧）

Markdown 允许你在同一层级混用 -、*、+。有时候，为了让列表看起来更丰富，或者区分不同的子项，你可以这么做：

## 项目会议议程

1. 开场
   - 欢迎致辞
   * 主持人介绍
     + 嘉宾入场

2. 核心议题
   - 预算讨论
   * 人员调整

注意： 虽然在语法上这是允许的，但强烈不建议在正式文档中频繁混用。因为很多静态博客生成器（如 Hexo、Hugo）或笔记软件（如 Notion、Obsidian）在渲染时，可能会因为符号不一致而产生奇怪的样式问题。保持统一，最安全。

第二关：有序列表的嵌套（1., 2.）

有序列表用的是数字加点。嵌套逻辑和无序列表一样，也是靠缩进。但这里有个大坑，很多人就在这里栽跟头。

2.1 标准嵌套写法

## 如何制作一杯咖啡

1. 准备器具
   - 咖啡机
   - 磨豆机
   - 滤纸
2. 研磨咖啡豆
   1. 称取 18 克豆子
   2. 调整研磨度（中细）
   3. 填入粉碗
3. 萃取
   - 预热机器
   - 开始萃取（25-30秒）

关键点解析：

  • 注意看第 2 步下面的子项：1., 2., 3.。
  • 这里的数字不一定非要连续，Markdown 解析器通常会根据缩进自动推断层级。但是！为了可读性和避免歧义，强烈建议从 1 开始重新编号，或者按逻辑顺序编号。

2.2 有序列表嵌套中的“自动重置”陷阱

这是初学者最容易困惑的地方。看下面这个例子：

1. 第一步
   1. 子步骤 A
   2. 子步骤 B
2. 第二步
   1. 子步骤 C
   2. 子步骤 D

结果：

  • 第一层的 1. 和 2. 是有序的。
  • 第二层的 1. 和 2. 也会自动从 1 开始，无论你在源码里写的是 1 还是 5。
  • 有些解析器会保持你写的数字，有些会重置。为了保险，永远写 1. 开始，让渲染器去处理。

第三关：无序与有序列表的“混血”嵌套

这是最复杂、也是最实用的场景。比如，你有一个有序的步骤，但每个步骤里又有无序的子项；或者反过来。

3.1 有序列表嵌套无序列表

## 开发环境搭建步骤

1. 安装 Node.js
   - 访问官网
   - 下载 LTS 版本
   - 运行安装程序
2. 配置环境变量
   - 设置 PATH
   - 验证安装（终端输入 `node -v`）
3. 安装 IDE
   - VS Code
   - WebStorm

代码示例：

1. 安装 Node.js
   - 访问官网
   - 下载 LTS 版本

解析： 当你在有序列表的数字后面，用 4 个空格缩进一个无序列表时，渲染器会正确识别。关键是：无序列表的 - 必须对齐在有序列表数字的下方，或者有明确的缩进。

3.2 无序列表嵌套有序列表

## 周末计划

- 周六
  1. 上午：睡到自然醒
  2. 下午：去图书馆
  3. 晚上：看电影
- 周日
  1. 上午：大扫除
  2. 下午：准备下周工作
  3. 晚上：聚餐

代码示例：

- 周六
  1. 上午：睡到自然醒
  2. 下午：去图书馆

解析： 这里同理，有序列表的 1. 前面需要 4 个空格缩进。

第四关：避坑指南 —— 那些让你头痛的常见错误

好了，基础讲完了。现在，我要把你可能会遇到的“坑”一个个挖出来。这些坑，每一个都足够让你debug半小时。

坑 1：缩进不一致（最常见！）

错误示范：

- 项目A
  - 子任务1
   - 子任务2  <!-- 这里只有2个空格，而上面是4个 -->

后果：

  • 在某些渲染器中，子任务2 会被当成顶级列表，和 项目A 平级。
  • 在另一些渲染器中，它可能根本没法正确渲染，或者直接忽略。

解决方案：

  • 统一使用 4 个空格作为一级缩进。
  • 开启编辑器的“显示空白字符”功能，肉眼检查每一行开头的空格数。
  • 绝对不要混合使用 Tab 和空格。

坑 2：列表中间插入了空行（破坏连续性问题）

Markdown 的列表识别依赖于“连续性”。如果你在列表项之间插入空行，有些解析器会认为列表结束了。

错误示范：

- 第一项
  - 子项1

  - 子项2  <!-- 前面有空行，子项2可能脱离子列表 -->
- 第二项

后果：

  • 子项2 可能变成顶级列表，或者样式错乱。

解决方案：

  • 在嵌套列表中，尽量避免在子项之间插入空行。如果必须换行，使用 HTML 的 <br> 标签，或者确保缩进保持连贯。
  • 或者，直接用代码块包裹，避免解析。

坑 3：数字序号的“硬编码”陷阱

错误示范：

1. 步骤一
   5. 子步骤一  <!-- 你写了5，但渲染器可能还是显示1 -->
2. 步骤二

后果：

  • 虽然大多数渲染器会自动重置为 1，但有些旧的或特定的解析器（如某些论坛系统）会忠实显示你写的数字，导致序列变成 1, 5, 2… 这看起来很傻。

解决方案：

  • 永远从 1. 开始写有序列表的嵌套项。
  • 不要依赖渲染器自动修正你的错误，主动写对。

坑 4：用中文标点或全角空格

错误示范：

－ 第一项   <!-- 用的是全角短横线，或者中文的“-” -->

后果：

  • 解析器无法识别这是列表，直接当成普通文本显示。

解决方案：

  • 确保使用英文半角字符：-、*、+、.。
  • 确保使用英文半角空格。中文全角空格（　）会导致缩进失效或错位。

坑 5：在列表项中使用代码块，缩进爆炸

这是一个高级问题。如果你想在列表项里写代码，你需要双重缩进。

错误示范：

1. 安装依赖
   - npm install
     ```javascript
     console.log('hello');
     ```

后果：

  • 代码块的缩进可能不够，或者导致列表解析失败。

解决方案：

  • 使用 4 个空格 缩进列表项，然后代码块再额外缩进 4 个空格（总共 8 个空格，或者根据你代码块的规则）。
  • 或者，使用反引号包裹代码，但确保缩进层级正确。
1. 安装依赖
   - npm install
     ```javascript
     console.log('hello');
     ```

注意：上面的代码块前面需要 6 或 8 个空格，具体取决于你的列表层级。

第五关：实战演练 —— 一个复杂的嵌套示例

让我们把今天学到的所有知识，整合到一个真实的文档场景中。假设你在写一个“如何配置 Git”的教程。

# 如何配置 Git

## 1. 初始化仓库

首先，进入你的项目目录：

```bash
cd my-project

然后初始化 Git：

git init

2. 配置用户信息

你需要设置用户名和邮箱，这样每次提交都会带上这些信息：

  1. 设置用户名
    • 打开终端
    • 输入以下命令： 
      
git config --global user.name "Your Name"
  2. 设置邮箱
    • 同样在终端输入： 
      
git config --global user.email "your@email.com"

3. 常用命令速查

  • 查看状态：git status
  • 添加文件：git add .
  • 提交更改：
    1. 暂存所有更改
      • 使用 git add .
    2. 提交并写注释
      • 使用 git commit -m "初始提交"

4. 推送代码

  • 连接到远程仓库
    • 添加远程地址
     git remote add origin https://github.com/user/repo.git
    • 推送代码
      • 首次推送：git push -u origin master
      • 后续推送：git push

”`

为什么这个例子好？

  • 它有有序列表（步骤 1, 2, 3）。
  • 它在有序列表中嵌套了无序列表（查看状态、添加文件、提交更改）。
  • 它在嵌套列表中又嵌入了代码块（git config 命令）。
  • 缩进层级清晰：一级列表顶格，二级列表 4 空格，三级列表 8 空格，代码块再额外 4 空格。

最后的话：如何验证你的列表写得对不对？

  1. 使用预览工具：Typora、VS Code 的 Markdown 预览插件、或者 GitHub 的预览功能。写完一行，看一眼效果。
  2. 在线校验器：如果不确定，可以复制到 StackEdit 或 Dillinger 这类在线 Markdown 编辑器里，它们对错误的容忍度较高，且能实时显示源码和渲染结果。
  3. 人眼检查：看缩进是否整齐。如果视觉上左对齐的字符不在同一垂直线上，那缩进很可能出错了。

记住，Markdown 的列表嵌套，本质上是用空格来暗示层级关系。只要你的空格打得足够整齐、足够一致，解析器就会乖乖听话。

希望这篇指南能帮你彻底告别列表嵌套的烦恼。如果还有疑问，欢迎随时问我——毕竟，我是 Agnes，专门帮你把复杂的事情讲简单。

-- 展开阅读全文 --