使用 markdownlint 规范 Markdown 文档

XOlDKING 发布于 2023/10/22

总计 1465 字｜更新于 2023/10/24｜- 次阅读｜- 条评论

系列 - Markdown 语法

本文介绍了如何安装并使用 markdownlint-cli2 规范 Markdown 文档。

markdownlint 是一款具有明确规则库的静态语法分析工具，旨在保证 Markdown 文档语法的标准和一致性。

markdownlint-cli2 基于 markdownlint 语法规范检查并修正 Markdown 文档，是一个语法规则配置灵活、运行快速的命令行工具。

安装

markdownlint-cli2 可通过 Homebrew 安装：

1
2
3
4
5


$ brew install markdownlint-cli2

# 查看版本号，确认安装成功
$ markdownlint-cli2
markdownlint-cli2 v0.10.0 (markdownlint v0.31.1)

配置

配置规则

注意

笔者选用形式最简洁的 YAML 格式进行配置，其他格式配置文件请参考 markdownlint-cli2 - Configuration 进行配置。

在项目目录下新建 .markdownlint.yaml，作为 markdownlint 的规则配置文件：

1

vim .markdownlint.yaml

参考以默认参数完全配置的 markdownlint.yaml 文件以及 Markdown 语法规范：markdownlint ，按照自己的需求修改配置，只需添加与默认配置不同的配置项即可。

推荐使用易于理解的规则别名代替规则编号 MD0XX。
使用标签可以同时启用或禁用该标签组下的所有规则。
例如 ol: false 可以同时禁用涉及有序列表的 MD029、MD030、MD032 规则。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


# 默认启用所有配置项
default: true

extends: null

# MD003 标题格式选取最简洁的 ATX 标题样式
heading-style:
    style: "atx"

# MD004 无序列表前缀统一使用加号 +
ul-style:
    style: "plus"

# MD007 嵌套列表缩进 4 空格
ul-indent:
    indent: 4

# MD013 不限制每行字符数
line-length: false

# MD024 “兄弟”标题内容不可重复
no-duplicate-heading:
    siblings_only: true

# MD029 有序列表前缀编号依次递增
ol-prefix:
    style: "ordered"

# MD030 多行列表项内容对齐
list-marker-space:
    ol_multi: 2
    ul_multi: 3

# MD033 允许使用 HTML 语法
no-inline-html: false

# MD035 水平分割线统一格式
hr-style:
    style: "---"

# MD046 统一使用围栏式代码块
code-block-style:
    style: "fenced"

# MD048 代码块围栏样式为 ``` 
code-fence-style:
    style: "backtick"

# MD049 斜体样式为 _斜体_
emphasis-style:
    style: "underscore"

# MD050 粗体样式为 **粗体**
strong-style:
    style: "asterisk"

忽略文件

markdownlint-cli2 支持两种方式忽略文件：

命令行中运行 markdownlint-cli2 时通过在文件或目录前加 ! 或 # 忽略文件。
在 .markdownlint-cli2.yaml 配置文件中通过参数 ignores 忽略文件。

.markdownlint-cli2.yaml 是 markdownlint-cli2 的配置文件，除了支持 markdownlint 规则配置外，还支持导入自定义规则，导入 markdown-it 插件，自定义输出格式等。

临时禁用规则

参考

临时禁用规则请参考 markdownlint - Configuration。

在 Markdown 文档中适当位置加入下述 HTML 注释，可以在文档的指定范围内灵活启用或禁用 markdownlint 规则：

：
禁用所有规则。
：
启用所有规则。
：
在本行禁用所有规则。
：
在下一行禁用所有规则。
：
禁用指定编号的规则。
：
启用指定编号的规则。
：
在本行禁用指定编号的规则。
：
在下一行禁用指定编号的规则。
：
记录当前规则配置。
：
恢复之前记录的规则配置。

规则编号也可用规则别名或标签代替。

示例：临时禁用所有规则，然后恢复文档之前的规则配置

1
2
3
4


<!-- markdownlint-capture -->
<!-- markdownlint-disable -->
本行不应用任何规则检查
<!-- markdownlint-restore -->

上述注释仅对注释所在行（或其下一行）之后的文档生效。若希望注释不受其在文档中位置的限制，对整个文档的内容生效，可以使用如下注释格式：

：
在整个文档中禁用所有规则。
：
在整个文档中启用所有规则。
：
在整个文档中禁用指定编号的规则。
：
在整个文档中启用指定编号的规则。

对整个文档生效的注释方式支持 JSON 格式的规则配置：

1
2
3
4
5
6
7
8


<!-- markdownlint-configure-file
{
  "hr-style": {
    "style": "---"
  },
  "no-trailing-spaces": false
}
-->

运行

1
2
3
4
5


# 检查指定的 Markdown 文档
markdownlint-cli2 "path/to/file.md"

# 使用指定的配置文件，检查并修正项目目录下（node_modules 目录除外）所有 Markdown 文档
markdownlint-cli2 --config "example.markdownlint.yaml" --fix "**/*.md" "#node_modules"

参数:

--config file：指定配置文件。
--fix：在源文件上直接修正违规语法。

【参考】：

markdownlint：Markdown 语法检查和纠正工具。
markdownlint-cli2：Markdownlint 命令行工具。