markdownlint 检查规则
本文介绍了 markdownlint v0.38.0 版本规则以及 openEuler Docs 仓的规则设置，参照依据 https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/Rules.md 。对 markdownlint 规则有任何疑问或交流，请联系 ECHO@ECHO。
markdownlint 介绍
markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置的规则对 Markdown 文件进行全面的检查。文档写作时可以借助 VSCode 等工具的 markdownlint 插件修复格式问题。
openEuler docs 仓规则设置
openEuler 规则采用如下方案：
- MD003 (标题样式) 规则将参数
style设置为atx。 - MD029（有序列表的前缀序号）规则将参数
style设置为ordered。 - 屏蔽 MD004（无序列表）这条规则。
- 屏蔽 MD007（无序列表缩进）这条规则。
- 屏蔽 MD009（行尾空格）这条规则。
- 屏蔽 MD013（行的长度）这条规则。
- 屏蔽 MD014（命令前使用$而不显示输出）这条规则。
- 屏蔽 MD020（closed atx样式的标题内没有空格）这条规则。
- 屏蔽 MD021（closed atx样式的标题内有多个空格）这条规则。
- 屏蔽 MD024（不能有重复内容的标题）这条规则。
- 屏蔽 MD025 （文档中有多个顶级标题）这条规则。
- 屏蔽 MD027（块引用符号后的多个空格）这条规则。
- 屏蔽 MD033（内联HTML）这条规则。
- 屏蔽 MD036（使用强调标记代替标题）这条规则。
- 屏蔽 MD046（代码块样式）这条规则。
- MD003 (标题样式) 规则将参数
ruby 文件的书写方式如下：
bashall rule 'MD003', :style => :atx rule 'MD029', :style => :ordered exclude_rule 'MD004' exclude_rule 'MD007' exclude_rule 'MD009' exclude_rule 'MD013' exclude_rule 'MD014' exclude_rule 'MD020' exclude_rule 'MD021' exclude_rule 'MD024' exclude_rule 'MD025' exclude_rule 'MD027' exclude_rule 'MD033' exclude_rule 'MD036' exclude_rule 'MD046'
规则介绍
MD001 - 标题级别一次只能增加一个级别
错误示例
text# Header1 ### Header3正确示例
text# Header1 ## Header2 ### Header3 #### Header4
MD003 - 标题样式
参数
style：指定文档标题的样式，有consistent、atx、atx_closed、setext、setext_with_atx、setext_with_atx_closed六种，默认为consistent。
错误示例
text# ATX style H1 ## Closed ATX style H2 ## Setext style H1 ===============正确示例
text# ATX style H1 ## ATX style H2
setext_with_atx 和 setext_with_atx_closed 设置允许在使用了 Setext 样式标题（只支持 1 级和 2 级标题）的文档中使用 3 级及以上的 ATX 样式标题：
正确示例
textSetext style H1 =============== Setext style H2 --------------- ### ATX style H3
说明
配置的标题样式可以是一个具体的样式（atx、atx_closed、setext、setext_with_atx、setext_with_atx_closed），也可以通过 consistent 要求所有标题样式与第一个标题样式匹配。 水平分隔线直接放在一行文本下方会将该行文本变成二级 Setext 样式标题，从而可能触发此规则。
MD004 - 无序列表样式
本仓已屏蔽这条规则。
参数
style：指定无序列表的样式，有consistent(定义时符号前后保持一致)、asterisk(用星号定义)、plus(用加号定义)、dash(用减号定义)、sublist(定义多重列表的时候用不同的符号定义)五种，默认为consistent。
错误示例
text* Item 1 + Item 2正确示例
text* Item 1 * Item 2
MD005 - 同一级别的列表项缩进不一致
错误示例
text* Item1 * nested item 1 * nested item 2 * A misaligned item正确示例
text* Item1 * nested item 1 * nested item 2 * nested item 3
MD007 - 无序列表缩进
本仓已屏蔽这条规则。
参数
ident：指定无序列表嵌套时缩进的空格数，默认值是2。start_indent：第一级缩进空格数，当 start_indented 启用时，默认值是2。start_indented：是否缩进列表的第一级，默认值是false。
错误示例
text* List item * Nested list item indented by 4 spaces正确示例
text* List item * Nested list item indented by 2 spaces
MD009 - 行尾空格
本仓已屏蔽这条规则。
参数
br_spaces：指定在行尾可以添加的空格的数目，默认值为0，空格数目建议大于等于2，如果小于2，会默认为0。list_item_empty_lines：允许列表项中的空行有空格，默认值为false。strict：包含不必要的换行，默认值为false。
正确示例
textText text text text[2 spaces]text- list item text [2 spaces] list item text
MD010 - 不能使用tab键缩进，要使用空格
参数
code_blocks：指定本条规则在代码块里是否 (true or false) 生效,默认是 true。ignore_code_languages：要忽略的围栏代码语言列表，默认是 []。spaces_per_tab：每个硬制表符对应的空格数，默认是 1。
错误示例
textSome text * hard tab character used to indent the list item正确示例
textSome text * Spaces used to indent the list item instead
MD011 - 反向链接语法
错误示例
text(Incorrect link syntax)[http://www.example.com]正确示例
text[Correct link syntax](http://www.example.com)
MD012 - 多个连续的空行
参数
maximum：指定文档中可以连续的最多的空行数，默认值是1。
错误示例
textSome text here Some more text here正确示例
textSome text here Some more text here
说明
如果代码块内有多个连续的空行，将不会触发此规则。 maximum参数可用于配置允许的最大连续空行数。
MD013 - 行的长度
本仓已屏蔽这条规则。
参数
line_length：指定行的最大长度，默认是80。heading_line_length：指定标题行的最大的长度，默认是80。code_block_line_length：代码块的最大字符数，默认是80。code_blocks：指定规则是否(true or false)对代码块生效，默认是true。tables：指定规则是否(true or false)对表格生效，默认是true。headings：指定规则是否(true or false)对标题生效，默认是true。stern：严格长度检查，默认是false。strict：严格长度检查，默认是false。
MD014 - 命令前使用$而不显示输出
本仓已屏蔽这条规则。
错误示例
textls cat foo less bar正确示例
textls cat foo less bartext$ ls foo bar $ cat foo Hello world $ cat bar baz在代码块中，终端命令前不需要要有$，但是如果代码中既有终端命令，也有命令的输出，则终端前可以有$。
MD018 - atx样式的标题后没有空格
错误示例
text#Header1 ##Header2正确示例
text# Header1 ## Header2
MD019 - atx样式的标题后有多个空格
错误示例
text# Header1 ## Header2正确示例
text# Header1 ## Header2
MD020 - closed atx样式的标题内没有空格
本仓已屏蔽这条规则。
错误示例
text#Header1# ##Header2##正确示例
text# Header1 # ## Header2 ##
MD021 - closed atx样式的标题内有多个空格
本仓已屏蔽这条规则。
错误示例
text# Header1 # ## Header2 ##正确示例
text# Header1 # ## Header2 ##
MD022 - 标题行的上下行应该都是空行
参数
lines_above：指定标题行上方的空行数，默认值是1。lines_below：指定标题行下方的空行数，默认值是1。
错误示例
text# Header1 Some text Some more text ## Header2正确示例
text# Header1 Some text Some more text ## Header2
MD023 - 标题必须从行首开始
错误示例
textSome text ## Indented header正确示例
textSome text ## Header
像块引用这样的场景会“缩进”行首，因此以下写法也是正确的：
正确示例
text> # Heading in Block Quote
MD024 - 不能有重复内容的标题
本仓已屏蔽这条规则。
参数
siblings_only：仅检查同级标题，默认是false。
错误示例
text# Some text ## Some text正确示例
text# Some text ## Some more text
如果参数siblings_only设置为 true，则允许不同父级下的标题重复（这在变更日志中很常见）：
text
# Change log
## 1.0.0
### Features
## 2.0.0
### FeaturesMD025 - 文档中有多个顶级标题
本仓已屏蔽这条规则。
参数
level：指定文档最高级的标题，默认值是1。front_matter_title：用于匹配 front matter 中标题的正则表达式，默认 ^\stitle\s[:=]。
错误示例
text# Top level header # Another top level header正确示例
text# Title ## Header ### Another header
MD026 - 标题行尾的标点符号
参数
punctuation：指定标题行尾不能有的标点符号，默认值是".,;:!?"。
错误示例
text# This is a header.正确示例
text# This is a header
MD027 - 块引用符号后的多个空格
本仓已屏蔽这条规则。
参数
list_items：包含列表项，默认是true。
错误示例
text> This is a block quote with bad indentation > there should only be one正确示例
text> This is a block quote with bad indentation > there should only be one
在块引用内推断预期的列表缩进可能比较困难；将list_items参数设置为 false 可对有序和无序列表项禁用此规则。
MD028 - 块引用内的空行
错误示例
text> This is a blockquote > which is immediately followed by > this blockquote. Unfortunately > in some parsers, this are treated as the same blockquote.正确示例
text> This is a blockquote. > > This is the same blockquote.
MD029 - 有序列表的前缀序号
参数
style：指定前缀序号的格式，有one(只用1做前缀)，ordered(从1开始的加1递增数字做前缀)两种，默认值是one。本仓设置为ordered。
错误示例
text1. Do this 1. Do that 1. Done正确示例
text1. Do this 2. Do that 3. Done
MD030 - 列表标记后的空格
参数
ul_single：无序列表单个段落的前缀符号和文字之间的空格数，默认值是1。ol_single：有序列表单个段落的前缀符号和文字之间的空格数，默认值是1。ul_multi：无序列表多个段落的前缀符号和文字之间的空格数，默认值是1。ol_multi：有序列表单个段落的前缀符号和文字之间的空格数，默认值是1。
错误示例
text* Foo * Bar * Baz正确示例
text* Foo * Bar * Baz
MD031 - 单独的代码块前后需要用空格隔开（除非是在文档的开头或者结尾）
错误示例
textSome text ``` Code block ``` ``` Another code block ``` Some more text正确示例
textSome text ``` Code block ``` ``` Another code block ``` Some more text
MD032 - 列表前后需要用空格隔开（除非是在文档的开头或者结尾）
错误示例
textSome text * Some * List 1. Some 2. List Some text正确示例
textSome text * Some * List 1. Some 2. List Some text
MD033 - 内联HTML
本仓已屏蔽这条规则。
参数
allowed_elements：允许的元素，默认值是 1。
错误示例
text<h1>Inline HTML header</h1>正确示例
text# Markdown header
说明
要允许特定的 HTML 元素，请使用allowed_elements参数。
MD034 - 使用纯URL
错误示例
textFor more information, see http://www.example.com/.正确示例
textFor more information, see <http://www.example.com/>.
MD035 - 水平线样式
参数
style：指定创建水平线的方式，有consistent、***、---或其他指定水平线的字符串，默认值是consistent。
错误示例
text--- - - - *** * * * ****正确示例
text--- ---
MD036 - 使用强调标记代替标题
本仓已屏蔽这条规则。
参数
punctuation：指定用于结尾的标点符号，以此符号结尾的强调不会被视为以强调代替标题，默认值是".,;:!?"
错误示例
text**My document** Lorem ipsum dolor sit amet... _Another section_ Consectetur adipiscing elit, sed to eiusmod正确示例
text# My document Lorem ipsum dolor sit amet... ## Another section Consectetur adipiscing elit, sed to eiusmod
MD037 - 强调标记内强调的符号和强调的文字之间不能有空格
错误示例
textHere is some ** bold ** text Here is some * italic * text Here is some more __ bold __ text Here is some more _ italic _ text正确示例
textHere is some **bold** text Here is some *italic* text Here is some more __bold__ text Here is some more _italic_ text
MD038 - 单反引号和之间的内容不能有空格
错误示例
text` some text ` `some text ` ` some text`正确示例
text`some text`
MD039 - 链接文本和包围它的中括号之间内容不能有空格
错误示例
text[ a link ](http://www.example.com/)正确示例
text[a link](http://www.example.com/)
MD040 - 代码块应指定代码块的编程语言
错误示例
text``` #!/bin/bash echo Hello world ```正确示例
text```bash #!/bin/bash echo Hello world ```常用的代码块编程语言
语言支持 关键字 Python python C cpp Java java Shell bash Markdown markdown JavaScript js CSS css SQL sql PHP php Text text XML html Bat bat Protocol Buffers protobuf
MD041 - 文件中的第一行应该是顶级标题
参数
level：指定文档最高级的标题，默认值是1。allow_preamble：允许标题前有内容，默认值是false。front_matter_title：用于匹配 front matter 中标题的正则表达式，默认值是^\stitle\s[:=]。
错误示例
textThis is a file without a header正确示例
text# File with header This is a file with a top level header
MD042 - 无空链接
错误示例
text[an empty link]()text[an empty fragment](#)正确示例
text[a valid link](https://example.com/)text[a valid fragment](#fragment)
MD043 - 必需的标题结构
参数
headings：标题列表，默认 []。match_case：匹配标题的大小写，默认值是false。
正确示例
text# Heading ## Item ### Detail
将headings参数设置为： [ "# Heading", "## Item", "### Detail" ]
MD044 - 专有名词应使用正确的大小写
参数
code_blocks：包含代码块，默认值是true。html_elements：包含 HTML 元素，默认值是true。names：专有名词列表，默认值是[]。
正确示例 语言“JavaScript”通常首字母 J 和 S 大写——尽管有时 s 或 j 以小写形式出现。要强制执行正确的大小写，请在 names 数组中指定所需的大小写。
[ "JavaScript" ]
MD045 - 图像应有替代文本（alt 文本）
正确示例
texttext![Alternate text][ref] ... [ref]: image.jpg "Optional title"
MD046 - 代码块样式
本仓已屏蔽这条规则。
参数
style：指定代码块定义格式，有fenced（使用三个反引号），indented（使用缩进），consistent（上下文一致）三种，默认值是fenced。
错误示例
textSome text. Code block Some more text.正确示例
textSome text. ```ruby Code block ``` Some more text.
MD046 - 代码块风格
参数
style：指定代码块定义格式，有consistent（一致），fenced（围栏式），indented（缩进式）三种，默认值是consistent。
错误示例
textSome text. # Indented code More text. ```ruby # Fenced code ``` More text.正确示例
textSome text. # Indented code More text. # Fenced code More text.
MD047 - 文件应以单个换行符结尾
错误示例
text# Header This file ends without a newline.[EOF]正确示例
text# Header This file ends with a newline. [EOF]
MD048 - 代码围栏风格
参数
style：指定代码块定义格式，有consistent（一致），backtick（反引号），tilde（波浪线）三种，默认值是consistent。
错误示例
text```ruby # Fenced code ``` ~~~ruby # Fenced code ~~~正确示例
text```ruby # Fenced code ``` ```ruby # Fenced code ```
MD049 - 强调样式
参数
style：指定代码块定义格式，有consistent（一致），asterisk（星号），underscore（下划线）三种，默认值是consistent。
错误示例
text*Text* _Text_正确示例
text*Text* *Text*
MD050 - 加粗样式
参数
style：指定代码块定义格式，有consistent（一致），asterisk（星号），underscore（下划线）三种，默认值是consistent。
错误示例
text**Text** __Text__正确示例
text**Text** **Text**
MD051 - 链接片段应有效
参数
ignore_case：忽略片段大小写，默认值是false。ignored_pattern：用于忽略额外片段的模式，默认为空字符串。
错误示例
text# Heading Name [Link](#fragment)正确示例
text# Heading Name [Link](#heading-name)
MD052 - 参考链接和图片应使用已定义的标签
参数
ignored_labels：需忽略的链接标签，默认值：["x"]。ignored_pattern：是否包含快捷语法，默认值是false。
参考链接和图片有以下三种形式： Full: [text][label] Collapsed: [label][] Shortcut: [label]
Full: ![text][image] Collapsed: ![image][] Shortcut: ![image]
正确示例
text[label]: https://example.com/label [image]: https://example.com/image
MD053 - 链接和图片参考定义应为必需
参数
ignored_definitions：要忽略的定义，默认值：["//"]。
正确示例
text[//]: # (This behaves like a comment)
MD054 - 链接和图片样式
参数
autolink：允许自动链接，默认值是true。collapsed：允许折叠参考链接和图片，默认值是true。full：允许完整参考链接和图片，默认值是true。inline：允许内联链接和图片，默认值是true。shortcut：允许快捷参考链接和图片，默认值是true。url_inline：允许内联链接使用 URL 作为文本，默认值是true。
正确示例
将 inline参数设置为 false将禁用内联链接和图片：
text
<https://example.com>将 inline参数设置为 false将禁用内联链接和图片：
text
[link](https://example.com)
将 full参数设置为 false将禁用完整参考链接和图片：
text
[link][url]
![image][url]
[url]: https://example.com将 collapsed参数设置为 false将禁用折叠参考链接和图片：
text
[url][]
![url][]
[url]: https://example.com将 shortcut参数设置为 false将禁用快捷参考链接和图片：
text
[url]
![url]
[url]: https://example.com将 url_inline参数设置为 false可防止使用具有相同绝对 URL 文本/目标且无标题的内联链接，因为此类链接可以转换为自动链接：
text
[https://example.com](https://example.com)要修复 url_inline违规，可使用更简单的自动链接语法：
text
<https://example.com>MD055 - 表格管道符样式
参数
style：表格管道符样式，可选值：consistent/ leading_and_trailing/ leading_only/ no_leading_or_trailing/ trailing_only，默认值是consistent。
错误示例
text| Header | Header | | ------ | ------ Cell | Cell |text| Header | Header | | ------ | ------ | | Cell | Cell | This text is part of the table正确示例
text| Header | Header | | ------ | ------ | | Cell | Cell |text| Header | Header | | ------ | ------ | | Cell | Cell | This text is part of the table
MD056 - 表格列数一致性
错误示例
text| Header | Header | | ------ | ------ | | Cell | Cell | | Cell | | Cell | Cell | Cell |正确示例
text| Header | Header | | ------ | ------ | | Cell | Cell | | Cell | Cell | | Cell | Cell |
MD058 - 表格前后应包含空白行
错误示例
textSome text | Header | Header | | ------ | ------ | | Cell | Cell | > Blockquote正确示例
textSome text | Header | Header | | ------ | ------ | | Cell | Cell | > Blockquote
MD059 - 链接文本应具有描述性
参数
prohibited_texts：禁止使用的链接文本，默认值：["click here","here","link","more"]。
错误示例
textSome text [click here](...) [link](...)正确示例
textSome text [Download the budget document](...) [CommonMark Specification](...)
VSCode 中 Markdown 插件
markdownlint 扩展库包含 markdown 文件规则库，以保证 markdown 文件与其标准保持一致。添加配置后，markdownlint 可以自动检查文档错误。
安装
- 按下
Ctrl_Shift+X以打开扩展选项卡。 - 输入
markdownlint以找到扩展。 - 点击
Install按钮，然后再点击Enable按钮。
配置
注意：VSCode 中 markdownlint 参照的版本是 David Anson 拟定的，与 openEuler 仓使用的 markdownlint 官方 v0.38.0 版本有差异。为了与 openEuler 仓配置的规则保持一致，可参考下方配置项。
在命令面板（
Ctrl+Shift+P）中输入Open Settings (JSON)命令。在 Json 对象中添加如下配置：
bash"markdownlint.config":{ "default":true, "MD003":{"style":"atx"}, "MD029":{"style":"ordered"}, "MD004":false, "MD007":false, "MD009":false, "MD013":false, "MD014":false, "MD020":false, "MD021":false, "MD024":false, "MD025":false, "MD033":false, "MD036":false, "MD042":false, "MD043":false, "MD044":false, "MD045":false, "MD046":false, "MD048":false, "MD049":false, "MD050":false, "MD051":false, "MD052":false, "MD053":false, "MD055":false, "MD056":false, "MD057":false }
遵循 木兰宽松许可证第2版（MulanPSL2）
遵循木兰宽松许可证第2版（MulanPSL2）
版权所有 © 2026 openEuler 保留一切权利