26 - MarkdownLint - Lint Markdown 文件

Markdown 格式不需要编辑器添加任何的支援就可以撰写，利用简单的语法就可以定义各种样式，是现今在写技术文件时的主流文件格式。

但是自由的写作方式却十分容易造成样式不一致的问题。

使 Markdown 的格式一致化 - Markdownlint

Markdownlint 是个用以规范 Markdown 写法的工具，最初是由 Ruby 开发而成，现在也有了 Node.js 的版本，这里会使用 Node.js 版本做说明。

Node.js 版本的 Markdownlint 所提供的 API 被许多工具使用， 我们使用 markdownlint-cli 作为执行的媒介。

它会使用其内建的规则加以限制来达到一致的写法规范。

安装 Markdownlint

markdownlint-cli 是个 npm 套件，需要先行安装：

npm install markdownlint-cli --save-dev

使用 Markdownlint

使用配置档 .markdownlint.js 决定要使用哪些规则：

module.exports = {
  default: false, // excludes all rules
  MD001: true, // enables rule MD001
  MD003: { style: 'atx_closed' }, // set parameter style of rule MD003 to atx_closed
  'first-line-heading': true, // enables alias first-line-heading
  atx_closed: true, // enables tag atx-closed
};

在 .markdownlintignore 中加入想要排除的档案或目录：

node_modules

设定完成後执行 Markdownlint ：

npx markdownlint --config .markdownlint.js --fix .

这个指令会依照 .markdownlint.js 所设定的方式规范专案下所有的 Markdown 档案。

指令

markdownlint 使用 --fix 时，会将所有可以修正的问题复写至原档案，对於无法修正的则会输出讯息。

指定档案

markdownlint 在指令後可以带入档名、目录名或是 glob 作为作用范围的设定。

使用 glob 时请用引号夹住，因在 Bash 中，会将 glob 转为多个档案并以空白区隔，例如 *.md 会被转为 a.md b.md ... ，对於只读取单一参数的选项或是指令会导致错误发生，这时使用 '*.md' 则可以避免问题。

设定规则

markdownlint-cli 预设情况下会采用所有规则。

想要自己修改规则时可以使用配置档来设定，配置档的支援格式有许多种，依照专案习惯使用即可。

markdownlint-cli 预设会找寻当前目录中是否有 .markdownlint.json 、 .markdownlint.yaml 或 .markdownlint.yml ，或是在当前目录以及父目录中寻找 .markdownlintrc 作为配置档。除了这些外其他任何合法的 JSON 、 JSONC 、 JS （使用 module.exports 导出配置）或 YAML 格式的档案都可以透过 --config 设定为配置档。

每个规则都为一对名称与值组成：

module.exports = {
  default: false, // excludes all rules
  MD001: true, // enables rule MD001
  MD003: { style: 'atx_closed' }, // set parameter style of rule MD003 to atx_closed
  'first-line-heading': true, // enables alias first-line-heading
  atx_closed: true, // enables tag atx-closed
};

名称可以是 default 、 rule 、 alias 或 tags ：

• default ：特殊属性，设为 true 会启用所有规则，反之设为 false 则关闭所有规则
• rule ：规则名称，对应至各个规则，像是范例中的 MD001 与 MD003
• alias ：规则别称，对应至各个规则的别名，例如范例中的 first-line-heading 是规则 MD041 的别名
• tags ：作用的标签，对应至各规则的所属标签，可以将其视为规则的群组，例如范例中的 atx_closed 包括了 MD020 与 MD021 两个规则

规则的值可以是布林或是物件：

• 布林：是否启用此规则
• 物件：配置规则设定

排除档案

markdownlint-cli 采用 .gitignore 的设定来排除档案，它会检查当前目录是否有 .markdownlintignore 以用作排除档案的依据。

与 VS Code 整合

首先，安装 Markdownlint 插件：

code --install-extension davidanson.vscode-markdownlint

如此一来， Markdownlint 插件会使用设定档 .markdownlint.js 的配置，在编辑器上显示各种提示。

接着我们要调整配置，使得档案在储存时执行 Markdownlint 修复档案内容：

{
  "editor.codeActionsOnSave": {
    "source.fixAll.markdownlint": true
  }
}

将设定存於专案中

为了让每次新开此专案的使用者都可以使用到 Markdownlint ，我们可以将设定配置在 .vscode 目录中。

首先，我们需要纪录要安装的插件，在 .vscode/extensions.json 中：

{
  "recommendations": ["davidanson.vscode-markdownlint"]
}

另外相关的设定也可以在 .vscode/settings.json 中纪录：

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

这样一来，开启此专案的新使用者就可以使用插件推荐清单安装 Markdownlint ，并将相关的配置做设定。

本文重点整理

• Markdown 作为文件格式，提供了许多语法来设定各种丰富的样式，但由於其极高的自由度，使得每个人在使用 Markdown 写文件时总会有自己的一套方法，这造成了写法不一致的问题。
• Markdownlint 作为 Markdown 格式的规范工具，提供了许多有用的规则，使用者利用这些规则来确保不同 Markdown 文件的一致性。
• 如果想要自己设定规则也可以建立配置档做相关的设定，并利用 .markdownlintignore 档案的设定排除特定的档案。
• 使用 VS Code 的 Markdownlint 插件，可以在储存时启动 Markdownlint 对 Markdown 做 lint。

参考资料

• GitHub: markdownlint/markdownlint
• GitHub: markdownlint/markdownlint Rules
• GitHub: DavidAnson/markdownlint
• GitHub: igorshubovych/markdownlint-cli