Markdownlint规则详解

前言

在使用VS code打markdown代码的时候，软件总是给我推荐markdownlint这款插件，我抱着好奇心下来看看，发现只是一个用来规范源代码的东西，用处不是很大，但是对代码可读性有一点的提升，这篇文章是关于markdownlint规则的描述，方便我自己和大家查阅。

---

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

标题只能逐级递增不能跳跃。

MD003 - Heading style

这指的是你的声明标题的风格不对，风格总共有(“consistent”, “atx”, “atx_closed”, “setext”, “setext_with_atx”“setext_with_atx_closed”)五种，简单来说就是你可以用默认的标题声明，像这种：

# ATX style H1
## ATX style H2

也可以这样：

# ATX style H1 #
## ATX style H2 ##

当你的标题只有两个的时候可以：

Setext style H1
===============
Setext style H2
---------------

当超过两个标题，而前两级标题又想用setext风格（如上图），markdownlint也支持混搭

Setext style H1
===============
Setext style H2
---------------
### ATX style H3

但是不能第一级用atx而第二级又用setext，总之用“#”之后所有的标题都只能用“#”来声明，前两级可选“=”与“-”

MD004 - Unordered list style

这个规则是说你在声明无序列表的时候在同一缩进（同一级）使用了不同的特殊符号，如：

* Item 1
+ Item 2
- Item 3

这里应该改成相同的特殊符号，如：

* Item 1
* Item 2
* Item 3

然而，markdownlint允许在不同级（不同缩进）使用不同的特殊符号，如：

	* Item 1
		+ Item 2
			- Item 3
		+ Item 4
	* Item 4
		+ Item 5

只需要确保同一缩进使用的是同一种符号就好（似乎markdownlint还能自动修复这个冲突）

MD005 - Inconsistent indentation for list items at the same level

同一级别列表缩进不一致，像这种：

	* Item 1
  		* Nested Item 1
  		* Nested Item 2
   		 * A misaligned item	

正确的做法是将同级列表缩进改成一致的

* Item 1
  * Nested Item 1    
  * Nested Item 2
  * Nested Item 3

而有序列表的一致可以有两种，左对齐和右对齐

...	// 左对齐 
8. Item
9. Item
10. Item
11. Item
...

... // 右对齐
 8. Item
 9. Item
10. Item
11. Item
...

MD007 - Unordered list indentation

缩进的空格不符合规定（默认是两格）

参数：
“ident”：指定无序列表嵌套时缩进的空格数，默认是2

MD009 - Trailing spaces

行尾最多添加俩个空格，似乎可以作为硬换行，但是我试了一下没用，在缩进和围栏里的代码块不受这条规则的限制，除非要创建换行符否则结尾的空格没啥用也不会影响内容的呈现

参数：
“br_spaces”：指定在行尾可以添加的空格数目，空格数目建议大于等于2，如果小于2，会默认为0，也就是不允许任何行尾的空格
“list_item_empty_lines”：字符串，指定在列表中是否(true or false)用默认的空格数缩进空行，有的解释器会要求列表中的空行要缩进

MD010 - Hard tabs

当你使用Tab来进行缩进的时候可能触发这个冲突，通常将Tab换成空格就好

参数：
“code_blocks”：指定本条规则在代码块里是否(true or false)生效，默认为true
“ignore_code_languages”：当上一个参数为true时，可以通过设置参数为想要忽略的语言列表，那么列表中的语言就不会受到这条规则的限制
“space_per_tab”：默认情况下需要将Tab替换为1个空格，可以通过这个参数调整替换的空格个数

MD011 - Reversed link syntax

当我们想将一段文字写为可以点击然后跳转到指定链接时，[]和()的顺序搞反了，这样子的链接是不生效的，正确的应该是这样：

[Correct link syntax](https://www.example.com/)

MD012 - Multiple consecutive blank lines

大量的连续空行就会触发这个提醒，但是代码块中的空行不会，除非在代码块里，否则空行不会影响内容的呈现

参数：
“maximum”：指定文档中可以连续的最多空行数，默认值是 1

MD013 - Line length

当行长超过指定值时会触发这个冲突（通常默认为80），url和图片等链接的引用始终不会触发，因为一般这些行无法拆分

参数：
“line_length”：指定行的最大长度，默认是 80
“heading_line_length”：指定标题行的最大长度，默认是 80
“code_block_line_length”：设定代码块的字符数，默认为80
“code_blocks”：指定规则是否 (true or false) 对代码块生效，默认 true
“tables”：指定规则是否 (true or false) 对表格生效，默认 true
“hesdings”：指定规则是否 (true or false) 对标题生效，默认 true
“stern”：允许不含空格的行超过最大值，默认 false

MD014 - Dollar signs used before commands without showing output

在shell命令的代码块内，可以在输入的命令前加$，但输出前不能加

MD018 - No space after hash on atx style heading

在atx风格的hash字符后面要加一个空格，即以“#”开头来声明的标题，需要在“#”后面加一个空格，如果没有加空格markdown会认为他是一段文本，连同“#”直接输出

MD019 - Multiple spaces after hash on atx style heading

有18就有19，当hash字符后的空格多于一个的时候就会触发这个冲突

MD020 - No space inside hashes on closed atx style heading

closed_atx风格的标题也要加空格

# Heading 1 #
## Heading 2 ##

MD021 - Multiple spaces inside hashes on closed atx style heading

同19，closed_atx风格的标题出现了太大空格（指超过1个）

MD022 - Headings should be surrounded by blank lines

任何风格的标题应该被空行包围，通过参数配置多个空行时要自定义MD012，确保这些空行不会触发这个冲突

参数：
“lines_above”：指定标题行上方的空行数，默认为 1
“lines_below”：指定标题行下方的空行数，默认为 1
注：当参数被配置为-1时意味着可以接受任意空行，如果要配置特定级别的标题指定对应的number[ ]就好

MD023 - Headings must start at the beginning of the line

标题要从行的开头开始，不能有任何缩进，存在缩进的行会被解析为常规文本

MD024 - Multiple headings with the same content

不同标题应该是不同的文本

参数：
“siblings_only”：默认为 false，设为 true 时，不同标题下的子标题内容可以重复。

MD025 - Multiple top-level headings in the same document

每个文档只能有一个h1（最高级的标题）

参数：
“level”：指定文档最高级的标题，默认是 1
“front_matter_title”：字符串，指定在文档开头处的 front matter 中的标题，这个标题将作为整篇文档的最高级标题，如果文档中再次出现最高级标题，将会给出警告，另外，如果不想在 front matter 中指定标题，就把本参数的值设置为"" 。

MD026 - Trailing punctuation in heading

标题末尾不应该有符号除了“？”，和HTML实体引用尾部的分号

参数：
“punctuation”：字符串，指定标题行尾不能有的标点符号，默认是".,;:!。，；：！"

MD027 - Multiple spaces after blockquote symbol

块引号符号后只能有一个空格

MD028 - Blank line inside blockquote

两个引用块之间不应存在空格，若需要生成两个引用块则应该在引用块之间加一些文本，若需要渲染成一个引用块则应该在空白行前加上”>“

MD029 - Ordered list item prefix

有序列表的表项没有按照正常顺序递增或者全为1或0，如：

1. Do this. 
2. Do that.
3. Done.

1. Do this. 
1. Do that.
1. Done.

0. Do this. 
0. Do that.
0. Done.

此规则支持用0表示同一缩进的表项

...
08. Item
09. Item
10. Item
11. Item
...

对于缩进不正确的代码块会触发此规则,这才是正确的：

1. First list

	```text
	Code block
	```

1. Second list

参数：
“style”：字符串，指定前缀序号的格式，(“one”,“ordered”,“one_or_ordered”,“zero”)，分别表示只用 1 做前缀，用从 1 开始的加 1 递增数字做前缀，只用 1 或者从 1 开始的加 1 递增数字做前缀，只用0 做前缀，默认值是 “one_or_ordered”。

MD030 - Spaces after list markers

列表声明后使用了不恰当的空格数，这会导致显示内容不恰当

参数：
“ul_single”,“ol_single”,“ul_multi”,“ol_multi”：分别规定无序列表单个段落，有序列表单个
段落，无序列表多个段落，有序列表多个段落与文本之间的空格数，默认是 1。

MD031 - Fenced code blocks should be surrounded by blank lines

代码块应该用空白行围起来，有些语法解析器可能不会解析未被空格包围的代码块

“list_items”：若将参数设置为false，则在列表中禁用此规则，默认为 true

MD032 - Lists should be surrounded by blank lines

列表应该用空白行包围起来，除非列表在文档开头或结尾，部分编译器不会解析没有前后空行的列表

MD033 - Inline HTML

文档内不应该有原始HTML的元素，但可以通过调整参数，使得特定的HTML元素可以使用

参数：
“allowed_elements”：自定义允许的元素，是一个字符串数组，默认是空 [ ]

MD034 - Bare URL used

url和邮箱地址应该用<>括起来，部分解析器不会将没有括起来的url解析为链接，如果想要直接显示url，使用’'将他括起来

Not a clickable link: `https://www.example.com`

在使用嵌套链接时

[text [shortcut] text](https://example.com)

要将 “[” 和 “]”转义

[link \[text\] link](https://example.com) 

MD035 - Horizontal rule style

声明水平线的方式不一样，如果用与文档第一次声明水平线不一样的方式声明水平线就会触发此规则

参数：
“style”：指定创建水平线的方式(“consistent”,“***”,“—”,“___”)，默认是"consistent"

MD036 - Emphasis used instead of a heading

不要使用强调等特殊文本替代标题，这条规则只会检查完全有特殊文本组成的段落，对于常规文本中的特殊文本不会被检查

参数：
“punctuation”：指定标点符号，以指定符号结尾的强调不会被视为以强调代替标题，默认值是".,;:!?。，；：！？"
注：MD026是标题不能以指定标点结尾，则可以通过设置指定标点让解析器认为这不是一个标题进而规避MD036的检查

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

用围栏代码块应该指定语言，如果不需要语法高亮可以指定语言为text

	```text    
	Plain text in a code block
	```

参数：
“allowed_languages”：可以通过以列表传入允许的语言，没有传入则任意语言都可以，默认[ ]
“language_only”：通过将该参数设置为true，则不允许代码块中出现额外的数据，默认为false

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

每个文档都应该有且仅有一个一级标题，如果以图片作为标题，此规则也适用于HTML标题

参数：
“level”：在外部添加h1（HTML标题）时，可以通过该参数修改文档最高标题
“front_matter_title”：指定在文档开头处的 front matter 中的标题，这个标题将作为整篇文档的最高级标题，另外，如果不想在 front matter 中指定标题，就把本参数的值设置为" "

MD042 - No empty links

不能添加空的链接文本

MD043 - Required heading structure

默认情况下不会触发这个规则，可通过参数设置，指定标题所需要遵循的结构

参数：
“headings”：通过传入标题结构的列表，来设定标题所需遵循的结构，可用“*”表示0或更多未指定的标题，用“+”表示1或更多未指定的标题
“match_case”：默认情况下文档中的标题的大小写不需要与级别匹配，如需匹配可以将参数设置为true

MD044 - Proper names should have the correct capitalization

正确输入指定名词大小写

参数：
“names”：在这个参数列表里的名称，其大小写是指定的
“code_blocks”：设置参数为false对代码块范围禁用此规则，默认为 true
"html_elements"设置参数为false对HTML元素禁用此规则，默认为 true

MD045 - Images should have alternate text (alt text)

图片应该设置一个替代文本，为无法看到图片的人描述图片的内容：

![Alternate text](image.jpg)

或者用HTMl的形式：

<img src="image.jpg" alt="Alternate text" />

MD046 - Code block style

声明代码块的风格应该一致，都用缩进或者围栏

参数：
“style”：指定代码块定义格式，有（“consistent”，“fenced”，“indented”）三种，分别代表：文档上下文一致，使用分隔符（三个反引号或三个波浪号）隔开，使用缩进，默认是上下文一致。

MD047 - Files should end with a single newline character

整个文档的末尾应该有一个空白行，某些解析器在解析不以换行符结尾的文件会出问题

MD048 - Code fence style

代码围栏的声明要一样，都为三个反引号或者三个波浪号

参数：
“style”: 指定声明代码块采用什么符号，有（“consistent”，“tilde”，“backtick”）三种，分别代表：上下文一致，使用波浪号，使用反引号，默认是consistent。

MD049 - Emphasis style

斜体的声明要使用一致的符号，单词的重音只能用“*”

参数：
“style”：指定强调用什么符号声明，有（“consistent”，“asterisk”，“underscore”），分别代表：上下文一致，使用星号，使用下划线，默认是上下文一致（“consistent”）。

MD050 - Strong style

加粗的声明要使用一致的符号，单词的重音只能用“*”

参数：
“style”：指定强调用什么符号声明，有（“consistent”，“asterisk”，“underscore”），分别代表：上下文一致，使用星号，使用下划线，默认是上下文一致（“consistent”）。

MD051 - Link fragments should be valid

标题链接要指向一个存在的标题

MD052 - Reference links and images should use a label that is defined

图片和链接应使用标签引用定义，方便在文档不同位置使用同一url，未引用的标签会被解析为文本

Full: [text][label] 
Collapsed: [label][]
Shortcut: [label]

Full: ![text][image]
Collapsed: ![image][]
Shortcut: ![image]

[label]: https://example.com/label
[image]: https://example.com/image

参数：
“shortcut_syntax”：默认为false，不会检查[exampl]中的文本是否引用，如果将参数改为true则所有”[]“生成警告，如果想继续输出括号，则需要使用转义字符“[”

MD053 - Link and image reference definitions should be needed

未使用的url引用要删除，同一标签多次定义的情况下（第一个定义有效），要将其他定义删除

参数：
“ignore_definitions”：忽略参数列表中的标签，对列表里标签进行注释而非引用，默认是 [“//”]

MD054 - Link and image style

默认情况下，三种引用格式都可用，通过调整参数触发这条规则

参数：
“autolink”：默认情况下自动将url转换为连接，设置参数为false禁用此功能
“inline”：默认情况下可通过的方式将[]内的内容解析为可点击跳转的图标，将参数设置为false禁用此功能
“full”：默认情况下可通过引用的方式用标签在文档多个地方嵌入url，通过设置参数为false禁用此功能
“collapsed”：通过将参数设置为false禁用折叠的url引用

[url][]

![url][]

[url]: https://example.com

“shortcut”：默认情况下可通过[]加引用创建快捷url引用，通过设置参数为false禁用此功能

[url]

![url]

[url]: https://example.com

“url_inline”：设置参数为false，防止一下情况发生：

[https://example.com](https://example.com)

可以将以上替换为直接写url或者：

<https://example.com>

MD055 - Table pipe style

表格的声明需要用“|”围起来，表格后紧随的文本会解析为表格内容，所以需要加“|”或者用空白行分开表格与文本

MD056 - Table column count

表格的标题行和分隔行要有相同的单元数，否则不会被识别为表格，每行单元格数要相同，额外的单元格会导致数据丢失

总结

以上，写了关于markdownlint的50多种规则，从触发条件以及参数修改等方面介绍了各个规则，希望能对看这篇文章的你有所帮助，原文文档在这