MkDocs 列表渲染问题修复¶

问题描述¶

MkDocs 生成的 HTML 中 Markdown 列表的格式与本地预览不一致，主要表现为：

序号没有正确渲染
缩进处理不正确
嵌套列表样式异常

根本原因¶

配置文件存在以下问题：

1. 缺失关键 Markdown 扩展¶

原始配置缺少以下必要的扩展：

toc - 目录和锚点支持
attr_list - 属性列表支持
def_list - 定义列表支持

2. YAML 语法错误¶

在 pymdownx.emoji 和 pymdownx.superfences 配置中，YAML 语法不正确：

# 错误写法
emoji_generator: !!python/name:material.extensions.emoji.to_svg "" # 注释

# 正确写法
emoji_generator: !!python/name:material.extensions.emoji.to_svg

3. 依赖包未安装¶

MkDocs 使用 pipx 安装时，没有包含必要的主题和插件：

mkdocs-material - Material 主题
mkdocs-material-extensions - Material 扩展
pymdown-extensions - Markdown 扩展
mkdocs-git-revision-date-localized-plugin - Git 修订日期插件
mkdocs-glightbox - 图片灯箱插件
mkdocs-minify-plugin - 压缩插件
mkdocs-mermaid2-plugin - Mermaid 图表插件

解决方案¶

1. 更新 `mkdocs.yml` 配置¶

在 markdown_extensions 部分添加缺失的扩展：

markdown_extensions:
- toc:
    permalink: true
    toc_depth: 3
- admonition
- attr_list
- def_list
- pymdownx.details
- pymdownx.superfences:
    custom_fences:
    - name: mermaid
      class: mermaid
      format: !!python/name:pymdownx.superfences.fence_code_format

2. 修复 YAML 语法错误¶

# 表情符号
- pymdownx.emoji:
    emoji_generator: !!python/name:material.extensions.emoji.to_svg

# 数学公式
- pymdownx.arithmatex:
    generic: true

3. 安装缺失的依赖¶

# 安装 Material 主题和核心扩展
/Users/jimmy/.local/pipx/venvs/mkdocs/bin/python -m pip install \
  mkdocs-material \
  mkdocs-material-extensions \
  pymdown-extensions

# 安装插件
/Users/jimmy/.local/pipx/venvs/mkdocs/bin/python -m pip install \
  mkdocs-git-revision-date-localized-plugin \
  mkdocs-glightbox \
  mkdocs-minify-plugin \
  mkdocs-mermaid2-plugin

4. 增强 CSS 样式¶

在 docs/stylesheets/extra.css 中添加列表样式修复：

/* 修复有序列表和无序列表的显示问题 */
.md-typeset ol,
.md-typeset ul {
  list-style: inherit;
  margin-left: 0;
  padding-left: 0;
}

.md-typeset ol {
  list-style-type: decimal;
}

.md-typeset ul {
  list-style-type: disc;
}

.md-typeset ol li,
.md-typeset ul li {
  margin-left: 1.25em;
  padding-left: 0.5em;
}

/* 嵌套列表的缩进 */
.md-typeset ol ol,
.md-typeset ol ul,
.md-typeset ul ol,
.md-typeset ul ul {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
  margin-left: 1.25em;
}

/* 二级列表样式 */
.md-typeset ol ol {
  list-style-type: lower-alpha;
}

.md-typeset ul ul {
  list-style-type: circle;
}

/* 三级列表样式 */
.md-typeset ol ol ol {
  list-style-type: lower-roman;
}

.md-typeset ul ul ul {
  list-style-type: square;
}

验证修复¶

1. 构建文档¶

cd /Users/jimmy/Workspace/github/rootsongjc/website
mkdocs build

2. 启动本地服务器¶

mkdocs serve

访问 http://127.0.0.1:8000 查看效果。

3. 测试列表渲染¶

创建测试文档检查以下内容：

有序列表数字是否正确显示
无序列表圆点是否正确显示
嵌套列表缩进是否正确
二级列表是否使用字母或空心圆
三级列表是否使用罗马数字或方块

列表项中包含代码块的正确写法¶

错误写法（会导致列表断开）¶

1. **第一项**

   ```bash
   command1
   ```

2. **第二项**

   ```bash
   command2
   ```

正确写法（保持列表连续）¶

1. **第一项** - 说明文字：

    ```bash
    command1
    ```

2. **第二项** - 说明文字：

    ```bash
    command2
    ```

关键点：

在列表项标题和代码块之间添加说明文字（如"运行以下命令："）
代码块使用 4 个空格缩进（而不是 3 个）
确保代码块和列表项之间有空行但保持正确缩进

列表样式层级¶

修复后的列表样式层级如下：

有序列表¶

第一级：阿拉伯数字 (1, 2, 3...)
第二级：小写字母 (a, b, c...)
1. 第三级：小写罗马数字 (i, ii, iii...)

无序列表¶

第一级：实心圆点 (disc)
第二级：空心圆 (circle)
- 第三级：方块 (square)

注意事项¶

pipx 环境：如果 MkDocs 是通过 pipx 安装的，必须在 pipx 虚拟环境中安装所有依赖
YAML 标签：!!python/name: 是 MkDocs 特有的 YAML 标签，不能用于 yaml.safe_load() 验证
CSS 优先级：自定义 CSS 需要确保选择器优先级足够高，能够覆盖主题默认样式
缓存清理：修改 CSS 后可能需要清理浏览器缓存才能看到效果

总结¶

通过以上修复，MkDocs 生成的 HTML 现在能够正确渲染 Markdown 列表，包括：

✅ 正确的序号显示
✅ 合适的缩进层级
✅ 嵌套列表的样式变化
✅ 列表项内段落的正确间距