如何让GitHub Pages Jekyll的Kramdown渲染带复选框的有序列表编号

解决Kramdown渲染带复选框有序列表丢失编号的问题 #

方案一：修改Kramdown配置（无需更换解析器） #

Kramdown默认会把带[x]/[ ]的列表项识别为无序列表任务项，直接替换掉有序列表的编号。只需在_config.yml中禁用任务列表功能即可解决：

markdown: kramdown
kramdown:
  task_list_opts:
    disable: true

修改后，你的原Markdown代码会正常渲染出带编号的有序列表，[x]/[ ]作为普通文本保留，完全匹配你期望的效果。同时Kramdown原生支持目录生成，只需在页面中添加：

* TOC
{:toc}

就能自动生成目录。

方案二：切换到GFM解析器（配合TOC插件） #

如果想保留复选框的视觉样式，可切换到GFM解析器。GFM不会将有序列表中的[x]/[ ]识别为任务项，因此有序列表编号会正常显示。

1. 修改_config.yml配置：

markdown: gfm
plugins:
  - jekyll-toc

2. 在需要生成目录的页面中添加：

* TOC {:toc}

GitHub Pages官方支持jekyll-toc插件，无需额外部署，即可同时实现有序列表编号保留和目录生成。

补充：自定义复选框样式（可选） #

若使用方案一，想让[x]/[ ]更像真实复选框，可添加自定义CSS：

li:contains("[x]")::before {
  content: "✓ ";
  color: #2eaadc;
  margin-right: 4px;
}
li:contains("[ ]")::before {
  content: "☐ ";
  color: #ccc;
  margin-right: 4px;
}

内容的提问来源于stack exchange，提问作者Gabriel Staples