使用 Markdownlint 对 Markdown 文本格式检查

Markdownlint 简介

Markdown 标记语言旨在易于阅读、编写和理解。它的灵活性既是优点也是缺点。语法众多，因此格式可能不一致。某些构造在所有解析器中都不能很好地工作，应该避免。CommonMark 规范标准化解析器。

Markdownlint 是一个用于 Node.js 的静态分析工具，有一个标准规范，用于强制执行 Markdown 文件的标准和一致性。

Markdownlint 插件使用

markdownlint提供了多种使用场景下的解决方案，如命令行，编辑器甚至 GitHub Action。因为我平时写 Markdown 文档都是使用 VSCode，所以介绍一下 VSCode 下的使用。其他编辑器包括 VIM，Sublime 也都支持，可以前往官网查阅方法。

VSCode 需要下载插件，Ctrl+Shift+X打开插件中心，搜索Markdownlint安装即可。

安装插件后打开 Markdown 文档，如果有不符合规范的语法将会警告标识。如，标题前后没有空行，将会标识：

提示违反了第 22 条规范，第 22 条规范的就是标题前后需要有空行隔开。

目前有 53 条规范，可以在markdownlint/Rules.md查看所有规范的内容。

当然这些规范也都可以自定义是否检查，比如第 24 条规定，文档内不可以有重复的标题，但是我就有重复标题的需求，那该如何关闭这个检查呢，Markdownlint 提供了配置的方式。

Ctrl+Shift+P打开运行窗口，输入 Markdownlint，找到Creat or open the markdownlint configuration file。

创建一个配置文件，并输入以下内容，表示关闭第 24 条规范的检查：

{
  "MD024": false,
}

这样文档中将不会有第 24 条规范的检查警告，其他检查同理。

Markdownlint 自定义规则

MD001 - Heading levels should only increment by one level at a time

标题等级一次只能增加一级，不能跨级。

原理：标题代表文档的结构，跳过时可能会造成混淆 - 特别是对于可访问性场景。

MD002 - First heading should be a top-level heading

文档的第一个标题必须是最高级的标题（标题等级 1 级到 6 级逐渐降低）

MD003 - Heading style

整篇文档需要采用一致的标题格式。

MD004 - Unordered list style

无序列表格式需要一致。

MD005 - Inconsistent indentation for list items at the same level

• 同一级的列表缩进必须一致
• 在有序列表中，前面的数字序号可以左对齐，也可以右对齐

MD006 - Consider starting bulleted lists at the beginning of the line

一级列表不能缩进。

如下为报错：

Some text

  * List item
  * List item

MD007 - Unordered list indentation

无序列表嵌套缩进时默认采用两个空格。

MD009 - Trailing spaces

行尾最多可以添加两个空格，超过会给出警告，两个空格正好可以用于换行。

MD010 - Hard tabs

不能使用 tab 键缩进，要使用空格。

原理：硬制表符通常由不同的编辑器以不一致的方式呈现，并且比空格更难处理。

MD011 - Reversed link syntax

当遇到看似链接的文本，但语法似乎已反转（[] 和 () 反转）时，将触发此规则。

MD012 - Multiple consecutive blank lines

文档中不能有连续的空行，在代码块中此规则不会生效。

MD013 - Line length

默认行的最大长度是 80，此规则对代码块、表格、标题也生效。

MD014 - Dollar signs used before commands without showing output

在代码块中，终端命令前不需要有美元符号 ($)
如果代码块中既有终端命令，也有命令的输出，则终端命令前可以有美元符号 ($)。

MD018 - No space after hash on atx style heading

在”atx”格式的标题中，#号和文字间需用一个空格隔开。

MD019 - Multiple spaces after hash on atx style heading

在”atx”格式的标题中，#号和文字间只能用一个空格隔开，不能有多余的空格。

MD020 - No space inside hashes on closed atx style heading

在”closed_atx”格式的标题中，文字和前后的#号之间需用一个空格隔开。

MD021 - Multiple spaces inside hashes on closed atx style heading

在”closed_atx”格式的标题中，文字和前后的#号之间只能用一个空格隔开，不能有多余的空格。

MD022 - Headings should be surrounded by blank lines

标题行的上下行必须都是空行。

MD023 - Headings must start at the beginning of the line

标题行不能缩进。

MD024 - Multiple headings with the same content

文档不能有内容重复的标题。

MD025 - Multiple top-level headings in the same document

同一文档只能有一个最高级的标题，默认是只能有一个 1 级标题。

MD026 - Trailing punctuation in heading

标题行末尾不能有以下标点符号。

MD027 - Multiple spaces after blockquote symbol

创建引用区块时，右尖括号 ( > ) 和文字之间有且只能有一个空格。

MD028 - Blank line inside blockquote

两个引用区块间不能仅用一个空行隔开或者同一引用区块中不能有空行，如果一行中没有内容，则这一行要用>开头。

MD029 - Ordered list item prefix

有序列表的前缀序号格式必须只用 1 或者从 1 开始的加 1 递增数字。

MD030 - Spaces after list markers

列表（有序、无序）的前缀符号和文字之间用 1 个空格隔开
在列表嵌套或者同一列表项中有多个段落时，无序列表缩进两个空格，有序列表缩进 3 个空格。

MD031 - Fenced code blocks should be surrounded by blank lines

单独的代码块前后需要用空行隔开（除非是在文档开头或末尾），否则有些解释器不会解释为代码块

MD032 - Lists should be surrounded by blank lines

列表（有序、无序）前后需要用空行隔开，否则有些解释器不会解释为列表。

列表的缩进必须一致。

MD033 - Inline HTML

文档中不允许使用 HTML 语句。

MD034 - Bare URL used

单纯的链接地址需要用尖括号 (<>) 包裹，否则有些解释器不会解释为链接。

MD035 - Horizontal rule style

创建水平线时整篇文档要统一 (consistent)，要和文档中第一次创建水平线使用的符号一致。

MD036 - Emphasis used instead of a heading

不能用加粗代替标题。

MD037 - Spaces inside emphasis markers

用于创建强调的符号和强调的的文字之间不能有空格。

MD038 - Spaces inside code span elements

当用单反引号创建代码段的时候，单反引号和它们之间的代码不能有空格
如果要把单反引号嵌入到代码段的首尾，创建代码段的单反引号和嵌入的单反引号间要有一个空格隔开。

MD039 - Spaces inside link text

链接名和包围它的中括号之间不能有空格，但链接名中间可以有空格。

MD040 - Fenced code blocks should have a language specified

单独的代码块（此处是指上下用三个反引号包围的代码块）应该指定代码块的编程语言，这一点有助于解释器对代码进行代码高亮。

MD041 - First line in a file should be a top-level heading

文档的第一个非空行应该是文档最高级的标题，默认是 1 级标题。

MD042 - No empty links

链接的地址不能为空。

MD043 - Required heading structure

要求标题遵循一定的结构，默认是没有规定的结构。

MD044 - Proper names should have the correct capitalization

指定一些名称，会检查它是否有正确的大写。

MD045 - Images should have alternate text (alt text)

图片链接必须包含描述文本（alt text）。

MD046 - Code block style

整篇文档采用一致的代码格式。

MD047 - Files should end with a single newline character

文档需用一个空行结尾。

MD048 - Code fence style

表示代码块的标记需要一直，可以是波浪号，也可以是点号。但是需要保持一致。

MD049 - Emphasis style should be consistent

强调符号需要一直，如斜体。

MD050 - Strong style should be consistent

加粗符号需要保持一致。

MD051 - Link fragments should be valid

锚点需要表示正确。