VuePress Markdown 任务列表插件配置

让你的 VuePress 站点中的 Markdown 文件支持任务列表。

任务列表就是带勾选框的清单。这个语法最早是 GitHub 在自己的 Markdown 方言里加的，用来在 issue 和 PR 描述里做待办清单，用得多了大家就习惯成自然，很容易以为它是 Markdown 标准的一部分。实际上 CommonMark 规范里没有它，GitHub 那边能用是因为 GFM 扩展了这一条。

所以同一段 - [ ] xxx，在 GitHub 上渲染成勾选框，粘到自己的博客里就只是一个字面带方括号的普通列表项。想在自己站点上得到一样的效果，需要给 markdown-it 补上这条解析规则。

我用它的场景主要是记录学习计划和功能清单，写的时候能直观看到进度，比纯文字描述「已完成」「待办」清楚。要注意的是博客里的任务列表是静态渲染出来的，不像 GitHub 上那样点一下就能改状态并保存，勾选状态由源文件决定。

配置

开关叫 tasklist，布尔值即可。这个插件只负责把语法转成带 checkbox 的列表结构，样式和主题走。

// .vuepress/config.ts
import { mdEnhancePlugin } from 'vuepress-plugin-md-enhance';

export default {
  plugins: [
    mdEnhancePlugin({
      // 启用任务列表
      tasklist: true,
    }),
  ],
};

// .vuepress/config.js
import { mdEnhancePlugin } from 'vuepress-plugin-md-enhance';

export default {
  plugins: [
    mdEnhancePlugin({
      // 启用任务列表
      tasklist: true,
    }),
  ],
};

语法

写法建立在普通无序列表之上，在列表标记后面加一对方括号表示状态。

• 使用 - [ ] 一些文字 渲染一个未勾选的任务项
• 使用 - [x] 一些文字 渲染一个勾选了的任务项 (我们也支持大写的 X)

有两个空格容易写错。未勾选那个方括号里必须是恰好一个空格，写成 [] 没有空格不会被识别。方括号和后面的文字之间也要有一个空格，- [x]内容 这样紧贴着写同样不生效。

列表标记用 -、*、+ 都可以，跟普通列表一致。任务项支持嵌套，子项缩进后能形成层级，但父项的勾选状态不会根据子项自动计算，各自独立。

例子

下面第一组是渲染效果，可以看到 A 是空框、B 打了勾；第二组是源码。

• [ ] 计划 A
• [x] 计划 B

- [ ] 计划 A
- [x] 计划 B

渲染出来的是一个 ul 列表，每项里放一个 input type="checkbox"，勾选态通过 checked 属性体现，同时列表本身会被去掉默认的圆点符号。

高级

默认行为够用，但有两个细节可以调。

除了在插件选项中设置 tasklist: true 之外，你还可以将对象作为选项传递给它。可用选项如下:

interface TaskListOptions {
  /**
   * 是否禁用 checkbox
   *
   * @default true
   */
  disabled?: boolean;

  /**
   * 是否使用 `<label>` 来包裹文字
   *
   * @default true
   */
  label?: boolean;
}

disabled 默认是 true，也就是勾选框渲染成禁用状态，点不动。这个默认值是合理的：文章是静态生成的，用户点开的勾选状态没有任何地方可以保存，刷新就没了，还会让人误以为改动生效了。改成 false 让它可点，只在很特定的场合有意义，比如页面上另有脚本读取这些勾选状态做交互。

label 控制的是要不要用 <label> 标签包住文字。默认包上，好处是点文字也能触发勾选框，点击热区从一个小方块扩大到整行，这是无障碍上的标准做法。配合 disabled: false 使用时这个差别很明显。如果主题的样式跟 label 打架，或者想自己完全接管这块结构，才需要关掉它。

传对象的写法就是把 tasklist: true 换成 tasklist: { disabled: false }，只写想改的字段，其余保持默认。