Markdown与规范化格式入门
Markdown与规范化格式入门
什么是Markdown？
不知道你之前是否了解过HTML，HTML是超文本标记语言，就是用标签的方式标记文章的文段布局，排版格式等等，就像是报纸的排版格式标准，对HTML感兴趣的话，可以去查看HTML（超文本标记语言） | MDN
类似的，Markdown 是一种轻量级标记语言，你可以使用它向纯文本文档添加格式元素。Markdown 由 John Gruber 于 2004 年创建，现在是世界上最流行的标记语言之一。
例如，要表示标题，你可以在标题前添加一个井号（例如，# 标题一）。或者要使短语变为粗体，你可以在短语前后添加两个星号（例如，此文本为粗体）。在文本中看到 Markdown 语法可能需要一段时间才能适应，如果你试过用VSCode打开后缀名为.md的文件，很有可能见到过这种格式的文本
上面这幅图就是使用MarkDown标记语言编写的开发文档。
为什么要用MarkDown？
你可能会好奇，我们明明有很不错的文本编辑器，比如微软的Microsoft Office Word，国内金山的WPS word，他们都可以非常方便的编辑文本，并且轻松的设置格式。
是的！的确如此，他们的软件确实很棒，不过不知道你有没有注意过，如果一台电脑上没有安装word，使用记事本打开大概率是一堆乱码：
从后缀名就能看出一些端倪，后缀名一般都是.doc，.docx这种格式的文件，这也就意味着只有特定的解析器才可以正确查看里面的数据。
刚才提到的word等文本编辑器就是一种所见即所得编辑器（WYSIWYG What you see is what you get编辑器）是一种允许用户在编辑内容时实时查看最终效果的工具。
刚才举的例子就能给我们提供一个使用MarkDown的理由：可以让有排版格式富文本文件兼容大多数设备，而不是让用户必须安装word才行（虽然现在绝大多数常用设备都是出厂就支持这些）
我们使用MarkDown还有很多更为明确的理由，MarkDown在某些领域确实有很不错的优点，不然也不会被大部分人认可，也不会成为AI大模型的默认输出格式。
以下是常见的使用MarkDown的理由（即优点）：
- Markdown 可用于一切。人们使用它来创建 网站、文档、笔记、书籍、演示文稿、电子邮件 和 技术文档。
- Markdown 是可移植的。包含 Markdown 格式文本的文件几乎可以使用任何应用程序打开。如果你决定不喜欢当前使用的 Markdown 应用程序，你可以将 Markdown 文件导入另一个 Markdown 应用程序。这与 Microsoft Word 等将内容锁定为专有文件格式的文字处理应用程序形成了鲜明的对比。
- Markdown 与平台无关。你可以在运行任何操作系统的任何设备上创建 Markdown 格式的文本。
- Markdown 具有未来性。即使你使用的应用程序在未来某个时间点停止工作，你仍然可以使用文本编辑应用程序阅读 Markdown 格式的文本。对于需要无限期保存的书籍、大学论文和其他里程碑式文档，这是一个重要的考虑因素。
- Markdown 无处不在。像 Reddit 和 GitHub 这样的网站支持 Markdown，并且许多桌面和基于 Web 的应用程序也支持它。
上面这段话摘自MarkDown官方教程，如果想更深入了解MarkDown可以转至该网站。
常见的MarkDown语法
如果你只是为了编写一些文章，中间可能加一些图片什么的，掌握一些简单的语法即可：
标题
要创建标题，请在单词或短语前添加井号 (#)。井号的数量应与标题级别相对应。例如，要创建三级标题 (<h3>)，请使用三个井号（例如，### 我的标题）。
| Markdown | HTML | 呈现的输出 |
|---|---|---|
# 一级标题 |
<h1>一级标题</h1> |
一级标题 |
## 二级标题 |
<h2>二级标题</h2> |
二级标题 |
### 三级标题 |
<h3>三级标题</h3> |
三级标题 |
#### 四级标题 |
<h4>四级标题</h4> |
四级标题 |
##### 五级标题 |
<h5>五级标题</h5> |
五级标题 |
###### 六级标题 |
<h6>六级标题</h6> |
六级标题 |
段落
要创建段落，请使用空行分隔一行或多行文本。
| Markdown | HTML | 呈现的输出 |
|---|---|---|
我真的很喜欢使用 Markdown。 我想从现在开始使用它来格式 化我所有的文档。 |
<p>我真的很喜欢使用 Markdown。</p> <p>我想从现在开始使用它来格式 化我所有的文档。</p> |
我真的很喜欢使用 Markdown。 我想从现在开始使用它来格式 化我所有的文档。 |
换行
要创建换行或新行 (<br>)，请使用两个或更多空格结束一行，然后键入回车。
| Markdown | HTML | 呈现的输出 |
|---|---|---|
这是第一行。 这是第二行。 |
<p>这是第一行。<br> 这是第二行。</p> |
这是第一行。 这是第二行。 |
加粗
要加粗文本，请在单词或短语前和后添加两个星号或下划线。要加粗单词中间的内容以示强调，请在字母周围添加两个星号，中间不要有空格。
| Markdown | HTML | 呈现的输出 |
|---|---|---|
我非常喜欢 **加粗文本**。 |
我非常喜欢 <strong>加粗文本</strong>。 |
我非常喜欢 加粗文本。 |
我非常喜欢 __加粗文本__。 |
我非常喜欢 <strong>加粗文本</strong>。 |
我非常喜欢 加粗文本。 |
Love**is**bold |
Love<strong>is</strong>bold |
Loveisbold |
斜体
要将文本斜体化，请在单词或短语前和后添加一个星号或下划线。要斜体化单词中间的内容以示强调，请在字母周围添加一个星号，中间不要有空格。
| Markdown | HTML | 呈现的输出 |
|---|---|---|
斜体文本是 *cat's meow*。 |
斜体文本是 <em>cat's meow</em>。 |
斜体文本是 cat's meow。 |
斜体文本是 _cat's meow_。 |
斜体文本是 <em>cat's meow</em>。 |
斜体文本是 cat's meow。 |
A*cat*meow |
A<em>cat</em>meow |
Acatmeow |
引用块
要创建引用块，请在段落前添加 >。
> Dorothy followed her through many of the beautiful rooms in her castle.
呈现的输出如下所示
多萝茜跟随她穿过城堡中许多美丽的房间。
包含多个段落的引用块
引用块可以包含多个段落。在段落之间的空白行上添加 >。
> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
呈现的输出如下所示
多萝茜跟随她穿过城堡中许多美丽的房间。
女巫命令她清洗锅碗瓢盆，打扫地板，并用木头生火。
有序列表
要创建有序列表，请添加带有数字和句号的行项目。数字不必按数字顺序排列，但列表应从数字一开头。
1. 第一个项目
2. 第二个项目
3. 第三项
1. 缩进项
2. 缩进项
4. 第四项
呈现的输出：
-
第一个项目
-
第二个项目
-
第三项
- 缩进项
- 缩进项
-
第四项
无序列表
要创建无序列表，请在行项目前添加破折号 (-)、星号 (*) 或加号 (+)。缩进一个或多个项目以创建嵌套列表。
- 第一项
- 第二项
- 第三项
- 缩进项
- 缩进项
- 第四项
-
第一项
-
第二项
-
第三项
- 缩进项
- 缩进项
-
第四项
代码
要表示一个单词或短语为代码，请用反引号 (`) 将其括起来。
| Markdown | HTML | 呈现的输出 |
|---|---|---|
| 在命令提示符下，键入`nano`。 | 在命令提示符下，键入 nano。 |
在命令提示符下，键入 nano。 |
转义反引号
如果你要表示为代码的单词或短语包含一个或多个反引号，你可以通过用双反引号 (``) 将单词或短语括起来来转义它。
| Markdown | HTML | 呈现的输出 |
|---|---|---|
| ``在你的 Markdown 文件中使用 `code`。`` | <code>在你的 Markdown 文件中使用 code。</code> | 在你的 Markdown 文件中使用 code。 |
代码块
要创建代码块，请将块的每一行至少缩进四个空格或一个制表符。
<html>
<head>
</head>
</html>
呈现的输出如下所示
<html>
<head>
</head>
</html>
链接
要创建链接，请用方括号括住链接文本，例如，[Duck Duck Go]，然后紧跟括号中的 URL，例如，(https://duckduckgo.com)。
My favorite search engine is [Duck Duck Go](https://duckduckgo.com).
呈现的输出如下所示
我最喜欢的搜索引擎是 Duck Duck Go。
转义字符
要显示一个文本字符，该字符原本用于格式化 Markdown 文档中的文本，请在字符前面添加一个反斜杠 ()。
\* Without the backslash, this would be a bullet in an unordered list.
呈现的输出如下所示
* 如果没有反斜杠，这将是无序列表中的项目符号。
可以转义的字符
可以使用反斜杠转义以下字符。
| 字符 | 名称 |
|---|---|
\ |
反斜杠 |
| ``` | 反引号（另请参阅 代码中的转义反引号） |
* |
星号 |
_ |
下划线 |
{ } |
大括号 |
[ ] |
方括号 |
< > |
尖括号 |
( ) |
圆括号 |
# |
井号 |
+ |
加号 |
- |
减号（连字符） |
. |
点 |
! |
感叹号 |
| |
管道（另请参阅 表格中转义管道） |
以上就是简单的MarkDown的基础用法了，很简单对吧。
如果你想深入学习MarkDown的话，可以移步你好！这里是 MARKDOWN 中文
常用的MarkDown编辑器
其实，我们也可以用记事本或是Vim，nano等很基础的编辑器编写MarkDown文件，但是这样会过于繁琐，你需要自己去输入每一个标签（不过我还说觉得用记事本写HTML更逆天）。所以，我们为什么不用一些好的MarkDown编辑器呢？
桌面端主流工具
(1) Typora 官方中文站（全平台）
-
优点：
- 即时渲染的所见即所得（WYSIWYG）体验
- 简洁无干扰的界面，支持主题自定义
- 表格、数学公式、代码块等高级语法友好
- 导出为 PDF/HTML/Word 等多种格式
-
缺点：
- 免费版已停更，需付费购买（一次性买断）
- 无插件生态，功能扩展性较弱
图片：
没错，我用的就是Typora，嘿嘿。
(2) Obsidian | 黑曜石（全平台）
-
优点：
- 双向链接和知识图谱功能，适合知识管理
- 强大的插件生态（社区插件超过 1000 个）
- 本地存储，数据隐私性强
- 支持 Markdown 扩展语法（如 Callout、Dataview）
-
缺点：
- 学习曲线陡峭，适合进阶用户
- 同步功能需付费（10 美元/月）
(3)VSCode + Markdown插件（全平台)
-
优点：
- 开发者友好，集成 Git 和代码调试
- 通过插件（如 Markdown All in One）实现高级功能
- 完全免费，开源可定制
-
缺点：
- 界面复杂，非开发者可能不适应
- 实时预览需分屏操作
我这里就先推荐这么多吧，想要更丰富的推荐请移步搜索引擎，接下来，我讲一下MarkdownLint。
CommonMark
Markdown 标记语言旨在易于阅读、编写和理解。它成功了--它的灵活性既是优点也是缺点。可以有多种样式，因此格式可能不一致;有些构造并非在所有解析器中都能很好地工作，应该避免。
MarkdownLint就是解决格式不一致的问题，其实更为广义地说，应该说是CommonMark，CommonMark是一个规范集，定义了Markdown文件的一些格式标准。Markdown的创始人John Gruber 对 Markdown 语法的规范描述没有明确指定语法。
在没有规范的情况下，早期的实施者参考原始代码来解决这些模糊之处。但原始代码漏洞百出，在很多情况下效果明显不佳，因此并不能令人满意地替代规范。
由于没有明确的规范，因此在过去 10 年中实现存在很大差异。因此，用户经常惊讶地发现，在一个系统（例如，GitHub wiki）上以一种方式呈现的文档在另一个系统上呈现不同（例如，使用 Pandoc 转换为文档集）。更糟糕的是，因为 Markdown 中的任何内容都不算作“语法错误”，所以通常不会立即发现差异。
Markdown 没有标准测试套件;MDTest 是我们最接近的东西，现在已经过时了。目前解决 Markdown 歧义和不一致的最佳方法是 Babelmark 3，它将 20+ 个 Markdown 实现的输出相互比较，看看是否出现共识。
为了解决这些问题，一群Markdown的爱好者创建了一个社区，为Markdown的格式规范而努力。
我们是一群 Markdown 爱好者，不断努力实现 CommonMark 的愿景——Markdown 的标准、可互作和可测试版本。
所以MarkdownLint其实只是CommonMark的一个被广泛接纳的实现。
以下是一些相关的网站：
CommonMark 规范。
GitHub 上的参考实现和验证测试套件。
通过 Discourse 的公共讨论区和邮件列表。
学习 Markdown 的快速参考卡和交互式教程。
由参考实现提供支持的实时测试工具。
而现在的CommonMark，经过无数人的反馈和改进，已经有了很完善的规范。
这次，我们积极拥抱一下这个规范，学习一下基于CommonMark的MarkdownLint
MarkdownLint
MD001- 标题级别一次只能递增一级
标签：headings
别名：heading-increment
当您跳过 Markdown 文档中的标题级别时，会触发此规则，例如：
# Heading 1
### Heading 3
We skipped out a 2nd level heading in this document
使用多个标题级别时，嵌套标题一次仅应该添加一级：
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
## Another Heading 2
### Another Heading 3
理由：标题代表文档的结构，跳过时可能会造成混淆 - 特别是对于辅助功能方案。更多信息：https://www.w3.org/WAI/tutorials/page-structure/headings/。
MD003 - 标题样式
标签：标题
别名：heading-style
参数：
style: 标题样式（string，默认consistent，值atx/atx_closed/consistent/setext/setext_with_atx/setext_with_atx_closed)
当同一文档中使用不同的标题样式时，此规则将被触发：
# ATX style H1
## Closed ATX style H2 ##
Setext style H1
===============
为解决此问题，请在整个文档中使用一致的标题样式：
# ATX style H1
## ATX style H2
setext_with_atx 和 setext_with_atx_closed 设置允许在具有 setext 样式标题的文档中使用 ATX 样式的三级或更高级别标题（setext 样式标题仅支持一级和二级标题）：
Setext style H1
===============
Setext style H2
---------------
### ATX style H3
注意：配置的标题样式可以是特定样式要求（atx， atx_closed、setext、setext_with_atx、setext_with_atx_closed），或者可以通过 consistent 要求所有标题样式与第一个标题样式保持一致。
注意：水平规则直接放置在一行文本下方可能会触发此规则，将该文本转换为二级 setext 样式的标题：
A line of text followed by a horizontal rule becomes a heading
---
原理：一致的格式使文档更易于理解。
MD004 - 无序列表样式
标签：bullet， ul
别名：ul-style
参数：
style：列表样式（string，默认为consistent，值为asterisk/consistent/dash/plus/sublist)
可修复：某些违规行为可以通过工具修复
当文档中用于无序列表项的符号与配置的无序列表样式不匹配时，将触发此规则：
* Item 1
+ Item 2
- Item 3
要解决此问题，请在整个文档中使用为列表项配置的样式：
* Item 1
* Item 2
* Item 3
配置的列表样式可以确保所有列表样式为特定符号（星号、加号、短横线），确保每个子列表具有与父列表不同的统一符号（子列表），或确保所有列表样式与第一个列表样式匹配（一致）。
例如，以下对于 sublist 样式是有效的，因为最外层缩进使用星号，中间缩进使用加号，而最内层缩进使用破折号：
* Item 1
+ Item 2
- Item 3
+ Item 4
* Item 4
+ Item 5
原理：一致的格式使文档更易于理解。
MD005 - 同一级列表项的缩进不一致
标签：bullet， indentation， ul
别名：list-indent
可修复：某些违规行为可以通过工具修复
当列表项被解析为处于同一级别但缩进不一致时，将触发此规则：
* 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 - 无序列表缩进
标签：bullet， indentation， ul
别名：ul-indent
参数：
indent: 缩进空格数（integer，默认值为2）start_indent: 首级缩进的空格数（当 start_indented 设置时）（integer，默认2）start_indented: 是否缩进第一级列表（boolean，默认为false）
可修复：某些违规行为可以通过工具修复
当列表项未按配置的空格数（默认：2个空格）缩进时，将触发此规则。
示例：
* List item
* Nested list item indented by 3 spaces
修正后的示例：
* List item
* Nested list item indented by 2 spaces
注意：此规则仅适用于其父列表均为无序列表的情况（否则，有序列表的额外缩进会干扰该规则）。
该 start_indented 参数允许列表的第一级按照配置的空格数进行缩进，而不是从零开始。该 start_indent 参数允许第一级列表使用不同的缩进量 比其他部分更多的空格（当未设置 start_indented 时忽略）。
原理：缩进 2 个空格可以使嵌套列表的内容与父列表内容开头对齐，当列表标记后使用单个空格时。缩进 4 个空格与代码块保持一致，且对编辑器实现更简单。此外，这可能是其他 Markdown 解析器的兼容性问题，因为它们要求 4 个空格的缩进。更多信息：Markdown 样式指南 。
注意：有关兼容性信息，请参阅 Prettier.md。
MD009 - 行尾空格
标签：whitespace
别名：no-trailing-spaces
参数：
br_spaces: 换行空格（integer，默认2）list_item_empty_lines: 允许列表项中的空行包含空格（boolean，默认为false）strict：包含不必要的换行（boolean，默认为false）
可修复：某些违规行为可以通过工具修复
此规则会在任何以意外空白字符结尾的行上触发。要修复此问题，请删除行尾的尾随空格。
注意：缩进代码块和围栏代码块允许使用尾随空格，因为某些语言需要它。
br_spaces 参数允许对此规则进行例外处理，允许特定数量的尾随空格，通常用于插入显式换行。默认值允许 2 个空格来表示硬换行（
元素）。
注意：您必须将 br_spaces 设置为≥2 的值，此参数才能生效。将 br_spaces 设置为 1 与设置为 0 的效果相同，即不允许任何尾随空格。
默认情况下，当使用允许的空格数量时，此规则不会触发，即使它不会创建硬换行（例如在段落末尾）。要报告此类实例，请将 strict 参数设置为 true。
Text text text
text[2 spaces]
使用空格缩进列表项内的空行通常不是必需的，但某些解析器需要这样做。将 list_item_empty_lines 参数设置为 true 允许这样做（即使当 strict 为 true 时）：
- list item text
[2 spaces]
list item text
原理：除用于创建换行外，尾部空白没有实际用途，且不影响内容的呈现。
MD010 - 硬制表符
标签：hard_tab， whitespace
别名：no-hard-tabs
参数：
code_blocks: 包含代码块（boolean，默认true）ignore_code_languages: 要忽略的围栏代码语言（string[]，默认[])spaces_per_tab：每个硬制表符的空格数（integer，默认值为1）
可修复：某些违规行为可以通过工具修复
此规则由包含硬制表符而非使用空格进行缩进的任何行触发。要修复此问题，请将任何硬制表符替换为空格。
示例：
Some text
* hard tab character used to indent the list item
修正后的示例：
Some text
* Spaces used to indent the list item instead
您可以选择排除代码块和代码片段的此规则。为此，将 code_blocks 参数设置为 false。默认情况下包含代码块和代码片段，因为 Markdown 工具对制表符的处理可能不一致（例如，使用 4 个空格与 8 个空格）。
当代码块被扫描时（例如默认情况下或当 code_blocks 为 true 时），可以将 ignore_code_languages 参数设置为一个应被忽略的语言列表（即允许使用硬制表符，但不要求）。这使得文档更容易包含需要硬制表符的语言代码。
默认情况下，此规则的违规行为会通过将制表符替换为 1 个空格字符来修复。要使用不同数量的空格，请设置 spaces_per_tab 将参数设置为您想要的值。
理由：硬制表符常被不同的编辑器不一致地渲染，并且比空格更难处理。
MD011 - 反向链接语法
标签：链接
别名：no-reversed-links
可修复：某些违规行为可以通过工具修复
当遇到看起来像是链接的文本，但语法似乎被反转了（[] 和 () 的顺序颠倒）时，会触发此规则：
(Incorrect link syntax)[https://www.example.com/]
要修复此问题，请将 [] 和 () 的位置互换：
[Correct link syntax](https://www.example.com/)
注意：Markdown Extra 风格的脚注不会触发此规则：
For (example)[^1]
理由：反向链接无法呈现为可用的链接。
MD012 - 多个连续空行
标签：blank_lines， whitespace
别名：no-multiple-blanks
参数：
maximum：连续空行数（integer，默认值1）
可修复：某些违规行为可以通过工具修复
当文档中存在多个连续的空行时，将触发此规则：
Some text here
Some more text here
要解决此问题，请删除有问题的行：
Some text here
Some more text here
注意：如果在代码块内有多个连续的空行，则此规则不会被触发（注意是代码块哦）。
注意：maximum 参数可用于配置连续空行的最大数量。
原理：除了在代码块中，空行没有实际用途，也不会影响内容的渲染。
MD013 - 行长度
标签：line_length
别名：line-length
参数：
code_block_line_length：代码块的字符数（integer，默认值80）code_blocks: 包含代码块（boolean，默认true）heading_line_length: 标题的字符数（integer，默认80)标题：包含标题（布尔值，默认为true）line_length: 字符数（integer，默认值80）stern：严格长度检查（boolean类型，默认值为false）strict：严格的长度检查（boolean，默认为false）tables：包含表格（boolean，默认为true）
当存在超过配置的 line_length（默认：80 个字符）的行时，将触发此规则。要修复此问题，请拆分该行 分成多行。要为标题设置不同的最大长度，请使用 heading_line_length。要为代码块设置不同的最大长度，请使用 代码块行长度
当配置的行长度之外没有空白时，此规则有一个例外。这使您可以包含长 URL 等项目，而无需被迫在中间断开。要禁用此例外，请设置 strict 将参数设置为 true，当任何行过长时将会报告问题。要警告那些过长但可以修复的行，同时允许没有空格的长行，请将 stern 参数设置为 true。
例如（假设正常行为）：
IF THIS LINE IS THE MAXIMUM LENGTH
This line is okay because there are-no-spaces-beyond-that-length
This line is a violation because there are spaces beyond that length
This-line-is-okay-because-there-are-no-spaces-anywhere-within
在 strict 模式下，上述最后三行都是违规的。在 stern 模式下，上面中间两行都是违规的，但最后一行是正常的。
您可以选择排除代码块、表格或标题的此规则。为此，请将 code_blocks、tables 或 headings 参数设置为 false。
代码块默认包含在此规则中，因为这通常是文档可读性的要求，并且暂时与代码规则兼容。然而，某些语言不适合短行。
包含链接/图像引用定义的行以及仅包含链接/图像（可能使用（强）强调）的独立行（即不属于段落的一部分）始终免于此规则（即使在 strict 模式下），因为通常无法在不破坏 URL 的情况下拆分此类行。
原理：在某些编辑器中，过长的行可能难以处理。更多信息：https://cirosantilli.com/markdown-style-guide#line-wrapping。
MD014 - 在命令前使用美元符号但未显示输出
标签：代码
别名：commands-show-output
可修复：某些违规行为可以通过工具修复
当存在显示要输入的 shell 命令的代码块，并且所有 shell 命令前面都带有美元符号($)时，会触发此规则：
$ ls
$ cat foo
$ less bar
在这种情况下，美元符号是不必要的，不应包含：
ls
cat foo
less bar
以美元符号开头的命令输出不会触发此规则：
$ ls
foo bar
$ cat foo
Hello world
$ cat bar
baz
由于某些命令不会产生输出，如果某些没有违反规则 命令没有输出：
$ mkdir test
mkdir: created directory 'test'
$ ls test
原理：使用美元符号更容易复制/粘贴，且噪音更少 在不必要时会被省略。参见 https://cirosantilli.com/markdown-style-guide#shell 代码中的美元符号 更多信息。
MD018 - atx 风格标题的 hash 符号后应有空格
标签：atx， headings， spaces
别名：no-missing-space-atx
可修复：某些违规行为可以通过工具修复
当 ATX 样式的标题中 hash 字符后缺少空格时，此规则将被触发：
#Heading 1
##Heading 2
要解决此问题，请在标题文本与哈希字符之间添加一个空格：
# Heading 1
## Heading 2
理由：违反此规则可能导致内容渲染不当。
MD019 - ATX 风格标题中哈希符号后的多个空格
标签：atx， headings， spaces
别名：no-multiple-space-atx
可修复：某些违规行为可以通过工具修复
当在 ATX 样式的标题中使用多个空格来分隔标题文本与哈希字符时，此规则将被触发：
# Heading 1
## Heading 2
要解决此问题，请在标题文本与哈希字符之间添加一个空格：
# Heading 1
## Heading 2
理由：多余的空格没有用途，不影响内容的渲染。
MD020 - 封闭式 ATX 风格标题的井号内应有空格
标签：atx_closed，headings，spaces
别名：no-missing-space-closed-atx
可修复：某些违规行为可以通过工具修复
当在闭合的 ATX 风格标题中的 hash 字符内部缺少空格时，此规则将被触发：
#Heading 1#
##Heading 2##
要解决此问题，请在标题文本与哈希字符之间添加一个空格：
# Heading 1 #
## Heading 2 ##
注意：如果标题的任一侧缺少空格，则此规则将被触发。
理由：违反此规则可能导致内容渲染不当。
MD021 - 闭合式 ATX 风格标题中的多个空格
标签：atx_closed，headings，spaces
别名：no-multiple-space-closed-atx
可修复：某些违规行为可以通过工具修复
当在闭合的 ATX 风格标题中，使用多个空格来分隔标题文本与哈希字符时，此规则将被触发：
# Heading 1 #
## Heading 2 ##
要解决此问题，请在标题文本与哈希字符之间添加一个空格：
# Heading 1 #
## Heading 2 ##
注意：如果标题的任一侧包含多个空格，则此规则将被触发。
理由：多余的空格没有用途，不影响内容的渲染。
MD022 - 标题前后应有空行
标签：blank_lines， headings
别名：blanks-around-headings
参数：
lines_above：标题上方的空行数（integer|integer[]，默认为1）lines_below: 标题下方的空行（integer|integer[]，默认为1）
可修复：某些违规行为可以通过工具修复
当标题（任何样式）前面或后面没有至少一个空行时，将触发此规则：
# Heading 1
Some text
Some more text
## Heading 2
要解决此问题，请确保所有标题前后都有空行（标题位于文档开头或结尾的情况除外）：
# Heading 1
Some text
Some more text
## Heading 2
lines_above 和 lines_below 参数可用于指定在每个标题上方或下方不同数量的空行（包括 0）。如果任一参数使用值 -1，则允许任意数量的空行。要单独自定义每个标题级别的上下空行数，请指定一个 number[]，其中值对应于 1-6 级标题（按顺序）。
注意：如果配置了 lines_above 或 lines_below 要求超过一个空行，MD012/no-multiple-blanks 也应进行自定义。此规则检查至少指定数量的空行；任何额外的空行将被忽略。
原理：除了美学原因外，一些解析器（包括 ）不会解析前面没有空行的标题，而是将它们解析为普通文本。
MD023 - 标题必须从行首开始
标签：headings， spaces
别名：heading-start-left
可修复：某些违规行为可以通过工具修复
当标题缩进一个或多个空格时，将触发此规则：
Some text
# Indented heading
要解决此问题，请确保所有标题都从行首开始：
Some text
# Heading
请注意，诸如块引用之类的场景会"缩进"行首，因此以下写法也是正确的：
> # Heading in Block Quote
原理：不从行首开始的标题将不会被解析为标题，而是会显示为普通文本。
MD024 - 多个具有相同内容的标题
标签：标题
别名：no-duplicate-heading
参数：
siblings_only: 仅检查同级标题（boolean，默认为false）
如果文档中有多个标题具有相同文本，则会触发此规则：
# Some text
## Some text
要解决此问题，请确保每个标题的内容各不相同：
# Some text
## Some more text
如果参数 siblings_only 设置为 true，则允许具有不同父级的标题重复（这在变更日志中很常见）：
# Change log
## 1.0.0
### Features
## 2.0.0
### Features
原理：一些 Markdown 解析器会根据标题名称生成锚点，内容相同的标题可能会导致问题。
MD025 - 同一文档中存在多个顶级标题
标签：标题
别名：single-h1， single-title
参数：
front_matter_title: 用于匹配前置内容中标题的正则表达式（string，默认为^\s*title\s*[:=]）级别：标题级别（整数，默认为1）
当文档中使用了顶级标题（文件的第一行是 h1 标题）并且文档中使用了多个 h1 标题时，此规则将被触发：
# Top level heading
# Another top-level heading
要修复此问题，请将文档结构化为包含单个 h1 标题作为文档标题。后续标题必须是较低级别的标题（h2、h3 等）：
# Title
## Heading
## Another heading
注意：level 参数可用于在 h1 被外部添加的情况下更改顶级标题（例如改为 h2）。
如果存在 YAML 前置内容且包含 title 属性（通常用于博客文章），此规则会将其视为顶级标题，并对任何后续的顶级标题报告违规。要在前置内容中使用不同的属性名，请通过 front_matter_title 参数指定正则表达式文本。要禁用此规则对前置内容的使用，请为 front_matter_title 指定 "" 值。 front_matter_title。
原理：顶级标题是文件第一行的 h1，用作文档的标题。如果使用此约定，则文档不能有多个标题，整个文档应包含在此标题内。
MD026 - 标题末尾标点符号
标签：标题
别名：no-trailing-punctuation
参数：
标点符号：标点字符（字符串，默认为.,;:!。，；：！）
可修复：某些违规行为可以通过工具修复
此规则会在行的最后一个字符为指定的常规或全角标点符号之一的标题上触发：
# This is a heading.
要解决此问题，请删除尾随标点符号：
# This is a heading
注意：punctuation 参数可用于指定哪些字符计入 作为标题结尾的标点符号。例如，您可以将其更改为 ".,;:" 以允许以感叹号结尾的标题。默认允许使用 ?，因为在常见问答风格文档的标题中很常见。将 punctuation 参数设置为 "" 允许所有字符 - 这相当于禁用该规则。
注意：HTML 实体引用的分号结尾 类似 ©、© 和 © 会被此规则忽略。
原理：标题不应为完整句子。更多信息： 标题末尾的标点符号 。
MD027 - 块引用符号后多个空格
标签：blockquote， indentation， whitespace
别名：no-multiple-space-blockquote
参数：
list_items：包含列表项（boolean，默认为true）
可修复：某些违规行为可以通过工具修复
当块引用符号（>）后有多于一个空格时，此规则将被触发：
> This is a blockquote with bad indentation
> there should only be one.
要修复，请删除任何多余的空格：
> This is a blockquote with correct
> indentation.
推断块引用中列表的预期缩进可能具有挑战性；将 list_items 参数设置为 false 可禁用此规则对有序和无序列表项的应用。
原理：一致的格式使文档更易于理解。
MD028 - 引用块内的空行
标签：blockquote， whitespace
别名：no-blanks-blockquote
当两个引用块之间仅由空行分隔时，此规则将被触发：
> This is a blockquote
> which is immediately followed by
> this blockquote. Unfortunately
> In some parsers, these are treated as the same blockquote.
要解决此问题，请确保任何相邻的块引用之间有一些文本内容：
> This is a blockquote.
And Jimmy also said:
> This too is a blockquote.
或者，如果它们应该是相同的引用，则在空白行的开头添加块引用符号：
> This is a blockquote.
>
> This is the same blockquote.
原理：一些 Markdown 解析器会将由一个或多个空行分隔的两个块引用视为同一个块引用，而其他解析器则会将它们视为不同的块引用。
MD029 - 有序列表项前缀
标签：ol
别名：ol-prefix
参数：
style：列表样式（string，默认为one_or_ordered，值为one/one_or_ordered/ordered/zero)
此规则针对有序列表触发，这些列表要么不以"1."开头，要么没有按配置的样式以递增的数字顺序作为前缀。也支持使用"0."作为第一个前缀或所有前缀的较少见模式。
当样式配置为'one'时的有效列表示例：
1. Do this.
1. Do that.
1. Done.
当样式配置为"有序"时，有效列表的示例：
1. Do this.
2. Do that.
3. Done.
0. Do this.
1. Do that.
2. Done.
当样式配置为'one_or_ordered'时，所有三个示例都是有效的。
当样式配置为'zero'时的有效列表示例：
0. Do this.
0. Do that.
0. Done.
所有样式的无效列表示例：
1. Do this.
3. Done.
此规则支持为有序列表项添加前缀零以实现统一缩进：
...
08. Item
09. Item
10. Item
11. Item
...
注意：此规则将报告以下类型的违规情况，其中不正确缩进的代码块（或类似元素）出现在两个列表项之间，并将列表"分割"成两部分：
1. First list
```text
Code block
```
1. Second list
解决方法是将代码块进行缩进，使其成为前一个列表项的一部分，如预期所示：
1. First list
```text
Code block
```
2. Still first list
原理：一致的格式使文档更易于理解。
MD030 - 列表标记后的空格
标签：ol， ul， whitespace
别名：list-marker-space
参数：
ol_multi：多行有序列表项的空格（integer，默认值为1）ol_single: 单行有序列表项的空格（integer，默认1)ul_multi：多行无序列表项的空格（integer，默认1)ul_single: 单行无序列表项的空格（integer，默认1)
可修复：某些违规行为可以通过工具修复
此规则检查列表标记（例如 -、*、+ 或 1.）与列表项文本之间的空格数量。
检查的空格数量取决于所使用的文档样式，但默认情况下，任何列表标记后应有1个空格：
* Foo
* Bar
* Baz
1. Foo
1. Bar
1. Baz
1. Foo
* Bar
1. Baz
文档样式可以独立更改无序列表项和有序列表项后的空格数量，也可以根据列表中每个项目的内容是单个段落还是多个段落（包括子列表和代码块）来进行调整。
例如，风格指南在 https://cirosantilli.com/markdown-style-guide#spaces-after-list-marker 指定如果列表中的每个项目都应该在列表标记后使用1个空格 列表适合放在单个段落中，但需要使用2或3个空格（用于有序） 以及无序列表，如果有多段内容的话 列表内：
* Foo
* Bar
* Baz
对
* Foo
Second paragraph
* Bar
或
1. Foo
Second paragraph
1. Bar
要解决此问题，请确保根据所选文档样式在列表标记后使用正确数量的空格。
理由：违反此规则可能导致内容渲染不当。
注意：有关兼容性信息，请参阅 Prettier.md。
MD031 - 围栏代码块应该被空行包围
标签：blank_lines， code
别名：blanks-around-fences
参数：
list_items：包含列表项（boolean，默认为true）
可修复：某些违规行为可以通过工具修复
当围栏代码块前面或后面没有空行时，此规则将被触发：
Some text
```
Code block
```
```
Another code block
```
Some more text
要解决此问题，请确保所有围栏代码块前后都有空行（除非该代码块位于文档的开头或结尾）：
Some text
```
Code block
```
```
Another code block
```
Some more text
将 list_items 参数设置为 false 可禁用此规则对列表项的应用。 如果需要创建列表，禁用此行为可能很有用 紧凑列表包含代码围栏。
理由：除了美学原因外，一些解析器（包括 kramdown）不会解析前后没有空行的围栏代码块。
MD032 - 列表应该被空行包围
标签：blank_lines， bullet， ol， ul
别名：blanks-around-lists
可修复：某些违规行为可以通过工具修复
当任意类型的列表前面或后面没有空行时，此规则将被触发：
Some text
* List item
* List item
1. List item
2. List item
***
在上面的第一种情况下，文本紧接在无序列表之前。在上面的第二种情况下，主题分隔符紧跟在有序列表之后。要修复对此规则的违反，请确保所有列表前后都有空行（除非列表位于文档的最开头或最末尾）：
Some text
* List item
* List item
1. List item
2. List item
***
请注意，以下情况不违反此规则：
1. List item
More item 1
2. List item
More item 2
尽管没有缩进，但文本"More item 2"被称为 延迟的续行并被视为第二个列表项的一部分。
原理：除了美学原因外，包括 kramdown 在内的一些解析器不会解析前后没有空行的列表。
MD033 - 内联 HTML
标签：html
别名：no-inline-html
参数：
allowed_elements: 允许的元素（string[]，默认为[]）
当在 Markdown 文档中使用原始 HTML 时，此规则将被触发：
<h1>Inline HTML heading</h1>
要解决此问题，请使用"纯"Markdown 而不是包含原始 HTML：
# Markdown heading
注意：要允许特定的 HTML 元素，请使用 allowed_elements 参数。
原理：Markdown 允许使用原始 HTML，但此规则适用于那些希望文档仅包含"纯"Markdown 的用户，或者那些将 Markdown 文档渲染为非 HTML 格式的用户。
MD034 - 使用了裸 URL
标签：链接， 网址
别名：no-bare-urls
可修复：某些违规行为可以通过工具修复
每当 URL 或电子邮件地址出现而没有周围的角度括号时，就会触发此规则：
For more info, visit https://www.example.com/ or email user@example.com.
要解决此问题，请在 URL 或电子邮件地址周围添加尖括号：
For more info, visit <https://www.example.com/> or email <user@example.com>.
如果URL或电子邮件地址包含非ASCII字符，即使有尖括号存在，也可能无法按预期处理。在这种情况下， percent-encoding 可用于符合 URL 和电子邮件所需的语法。
注意：要包含裸露的 URL 或电子邮件地址而不将其转换为链接，请将其包裹在代码跨度中：
Not a clickable link: `https://www.example.com`
注意：以下情况不会触发此规则，因为它可能是一个快捷链接：
[https://www.example.com]
注意：以下语法会触发此规则，因为嵌套链接可能是快捷链接（优先级更高）：
[text [shortcut] text](https://example.com)
为避免这种情况，请对两个内部括号进行转义：
[link \[text\] link](https://example.com)
理由：没有尖括号，某些 Markdown 解析器不会将裸露的 URL 或电子邮件地址转换为链接。
MD035 - 水平规则样式
标签：hr
别名：hr-style
参数：
style: 水平规则样式 (string, 默认consistent)
当文档中使用了不一致的水平规则样式时，将触发此规则：
---
- - -
***
* * *
****
要解决此问题，请在所有地方使用相同的水平规则：
---
---
配置的样式可以确保所有水平规则使用特定字符串，或者确保所有水平规则与第一个水平规则匹配（consistent）。
原理：一致的格式使文档更易于理解。
MD036 - 使用了强调（加粗）而非标题
标签：emphasis， headings
别名：no-emphasis-as-heading
参数：
标点符号：标点字符（字符串，默认为.,;:!?。，；：！？）
此检查查找使用强调文本（即粗体或斜体）来分隔部分的情况，此时应使用标题代替：
**My document**
Lorem ipsum dolor sit amet...
_Another section_
Consectetur adipiscing elit, sed do eiusmod.
要解决此问题，请使用 Markdown 标题而非强调文本来表示章节：
# My document
Lorem ipsum dolor sit amet...
## Another section
Consectetur adipiscing elit, sed do eiusmod.
注意：此规则查找完全由强调文本组成的单段落。它不会触发常规文本中的强调、多行强调段落或以标点符号（普通或全角）结尾的段落。与规则 MD026 类似，您可以配置哪些字符被识别为标点符号。
原理：使用强调而非标题可防止工具进行推断 文档的结构。更多信息： https://cirosantilli.com/markdown-style-guide#emphasis-vs-headers。
MD037 - 强调（加粗）标记内的空格
标签：emphasis， whitespace
别名：no-space-in-emphasis
可修复：某些违规行为可以通过工具修复
当使用强调标记（粗体、斜体）时，标记与文本之间有空格，则会触发此规则：
Here is some ** bold ** text.
Here is some * italic * text.
Here is some more __ bold __ text.
Here is some more _ italic _ text.
要解决此问题，请删除强调标记周围的空格：
Here is some **bold** text.
Here is some *italic* text.
Here is some more __bold__ text.
Here is some more _italic_ text.
原理：只有当星号/下划线没被空格包围时，才会被解析为强调。此规则试图检测它们被空格包围的情况，但看起来作者本意是想要强调文本。
MD038 - 代码片段元素内的空格
标签：code， whitespace
别名：no-space-in-code
可修复：某些违规行为可以通过工具修复
此规则针对代码片段中起始或结束反引号旁存在不必要空格的内容触发：
`some text `
` some text`
` some text `
要解决此问题，请删除开头和结尾的多余空格字符：
`some text`
注意：规范允许单个前导和尾随空格，解析器会将其删除以支持以反引号开头或结尾的代码片段：
`` `backticks` ``
`` backtick` ``
注意：当输入中存在单空格填充时，它将被保留（即使没有必要）：
` code `
注意：规范允许仅包含空格的代码片段，这些片段也会被保留：
` `
` `
理由：违反此规则通常是无意的，并且可能导致内容呈现不当。
MD039 - 链接文本内的空格
标签：links，whitespace
别名：no-space-in-links
可修复：某些违规行为可以通过工具修复
此规则在链接文本周围有空格时触发：
[ a link ](https://www.example.com/)
要解决此问题，请删除链接文本周围的空格：
[a link](https://www.example.com/)
原理：一致的格式使文档更易于理解。
MD040 - 围栏代码块应指定语言
标签：code， language
别名：fenced-code-language
参数：
allowed_languages: 语言列表（string[]，默认值[]）language_only：仅要求语言（boolean，默认false）
当使用围栏代码块但未指定语言时，此规则将被触发：
```
#!/bin/bash
echo Hello world
```
要解决此问题，请为代码块添加语言说明符：
```bash
#!/bin/bash
echo Hello world
```
要显示不带语法高亮的代码块，请使用：
```text
Plain text in a code block
```
您可以配置 allowed_languages 参数来指定代码块可以使用的语言列表。语言区分大小写。默认值为 []，这意味着任何语言说明符都是有效的。
您可以防止围栏代码块的信息字符串中出现额外数据。为此，将 language_only 参数设置为 true。
带有前导/尾随空格（例如：js）或其他内容（例如： ruby startline=3) 将触发此规则。
原理：指定语言可以通过使用 正确的代码语法高亮。更多信息： https://cirosantilli.com/markdown-style-guide#option-code-fenced。
MD041 - 文件的第一行应该是顶级标题
标签：headings
别名：first-line-h1， first-line-heading
参数：
allow_preamble: 允许第一个标题前的内容（boolean，默认值false)front_matter_title: 用于匹配前置内容中标题的正则表达式（string，默认为^\s*title\s*[:=]）级别：标题级别（整数，默认为1）
此规则旨在确保文档具有标题，当文档的第一行不是顶级（HTMLh1）标题时触发：
This is a document without a heading
要解决此问题，请在文档开头添加一个顶级标题：
# Document Heading
This is a document with a top-level heading
因为 GitHub 上的项目通常使用图片作为标题的 README.md 并且该模式在 Markdown 中支持不佳，此规则也允许使用 HTML 标题。例如：
<h1 align="center"><img src="https://placekitten.com/300/150"/></h1>
This is a document with a top-level HTML heading
在某些情况下，文档的标题前可能会有目录之类的文本。这对可访问性来说并不理想，但可以通过将 allow_preamble 参数设置为 true 来允许这种情况。
This is a document with preamble text
# Document Heading
如果存在 YAML 前置内容并且包含一个 title 属性（通常用于博客文章），此规则将不会报告违规。要在前置内容中使用不同的属性名，请通过 front_matter_title 参数指定一个正则表达式的文本。要禁用此规则使用前置内容，请为 front_matter_title 指定 ""。
该 level 参数可用于在 h1 被外部添加的情况下更改顶级标题（例如：更改为 h2）。
理由：顶级标题通常作为文档的标题。更多信息：https://cirosantilli.com/markdown-style-guide#top-level-header。
MD042 - 禁止空链接
标签：links
别名：no-empty-links
当遇到空链接时，此规则将被触发：
[an empty link]()
要修复此违规，请为链接提供目标：
[a valid link](https://example.com/)
空的片段将触发此规则：
[an empty fragment](#)
但是非空片段不会：
[a valid fragment](#fragment)
理由：空链接无法引导用户到达任何地方，因此不具备链接功能。
MD043 - 必需的标题结构
标签：headings
别名：required-headings
参数：
headings: 标题列表 (string[], 默认值[])match_case：匹配标题的大小写（boolean，默认为false）
当文件中的标题与传递给规则的标题数组不匹配时，将触发此规则。它可用于为一组文件强制执行标准标题结构。
要求完全符合以下结构：
# Heading
## Item
### Detail
将 headings 参数设置为：
[
"# Heading",
"## Item",
"### Detail"
]
允许使用可选标题，结构如下：
# Heading
## Item
### Detail (optional)
## Foot
### Notes (optional)
使用特殊值 "*" 表示"零个或多个未指定的标题"或使用特殊值 "+" 表示"一个或多个未指定的标题"，并设置 headings 参数设置为：
[
"# Heading",
"## Item",
"*",
"## Foot",
"*"
]
允许单个必需标题根据项目名称变化：
# Project Name
## Description
## Examples
使用特殊值 "?" 表示"恰好一个未指定的标题"：
[
"?",
"## Description",
"## Examples"
]
当检测到错误时，此规则会输出第一个问题标题的行号（否则，它会输出文件的最后一行号）。
请注意，虽然 headings 参数为简单起见使用"## Text"的 ATX 标题样式，但文件可以使用任何支持的标题样式。
默认情况下，文档中标题的大小写不需要与 headings 匹配。要要求大小写完全匹配，请设置 match_case 参数设置为 true。
理由：项目可能希望在一组相似内容中强制执行一致的文档结构。
MD044 - 专有名词应具有正确的大小写
标签：spelling
别名：proper-names
参数：
code_blocks：包含代码块（boolean，默认true）html_elements: 包含 HTML 元素（boolean，默认true）names: 正确名称列表（string[]，默认[]）
可修复：某些违规可以通过工具修复
当 names 数组中的任何字符串没有指定的首字母大写时，将触发此规则。它可用于强制项目名称和产品名称使用标准的字母大小写。
例如，语言"JavaScript"通常使用大写的'J'和 'S'——尽管有时小写的's'或'j'也会出现。为了 强制正确的首字母大写，请在 names 数组中指定所需的大小写：
[
"JavaScript"
]
有时候，专有名词在不同的语境中可能会有不同的首字母大写形式。在这种情况下，将两种形式都添加到 names 数组中：
[
"GitHub",
"github.com"
]
将 code_blocks 参数设置为 false 以禁用代码块和跨度中的此规则。将 html_elements 参数设置为 false 以禁用 HTML 元素和属性（例如，当使用专有名词作为 a/href 或 img/src 路径的一部分时）。
理由：专有名词首字母大写不正确通常是错误。
MD045 - 图片应有替代文本（alt 文本）
标签：accessibility， images
别名：no-alt-text
当图片缺少替代文本（alt 文本）信息时，此规则会报告违规。
替代文本通常以内联方式指定：
或者使用引用语法：
![Alternate text][ref]
...
[ref]: image.jpg "Optional title"
或者使用 HTML：
<img src="image.jpg" alt="Alternate text" />
注意：如果使用 HTML aria-hidden 属性来隐藏图像以供辅助技术使用，则此规则不会报告违规：
<img src="image.jpg" aria-hidden="true" />
关于编写替代文本的指南可从 W3C 获取， 维基百科 ，和 其他位置 。
理由：替代文本对可访问性很重要，它描述了对于可能无法看到图像的人来说的图像内容。
MD046 - 代码块样式
标签：code
别名：code-block-style
参数：
style: 区块样式 (string，默认值consistent，有效值consistent/fenced/indented)
当文档中使用了不希望或有不同的代码块样式时，将触发此规则。
在默认配置中，此规则会报告以下文档的违规：
Some text.
# Indented code
More text.
```ruby
# Fenced code
```
More text.
要修复此规则的违规，请使用一致的样式（缩进或代码围栏）。
配置的代码块样式可以是特定的（fenced，indented），也可以要求所有代码块与第一个代码块匹配（consistent）。
理由：一致的格式使文档更易于理解。
MD047 - 文件应以单个换行符结束
标签：blank_lines
别名：single-trailing-newline
可修复：某些违规可以通过工具修复
当文件末尾没有单个换行符时，将触发此规则。
触发此规则的示例：
# Heading
This file ends without a newline.[EOF]
要修复违规，在文件末尾添加换行符：
# Heading
This file ends with a newline.
[EOF]
理由：某些程序在处理不以换行符结尾的文件时可能会遇到问题。
更多信息： 在文件末尾添加新行的意义是什么？
MD048 - 代码围栏样式
标签：code
别名：code-fence-style
参数：
style: 代码围栏样式（string，默认值consistent，有效值backtick/consistent/tilde）
当文档中用于代码围栏的符号与配置的代码围栏样式不匹配时，将触发此规则：
```ruby
# Fenced code
```
~~~ruby
# Fenced code
~~~
要修复此问题，请在整个文档中使用配置的代码围栏样式：
```ruby
# Fenced code
```
```ruby
# Fenced code
```
配置的代码围栏样式可以是一个特定的符号来使用（反引号， 波浪号）或者它可以要求所有代码围栏与第一个代码围栏匹配（一致）。
理由：一致的格式使文档更易于理解。
MD049 - 强调样式
标签: emphasis
别名: emphasis-style
参数：
style: 强调样式 (string，默认consistent，值asterisk/consistent/underscore)
可修复：某些违规可以通过工具修复
当文档中用于强调的符号与配置的强调样式不匹配时，将触发此规则：
*Text*
_Text_
要修复此问题，请在整个文档中使用配置的强调样式：
*Text*
*Text*
配置的强调样式可以是一个特定的符号来使用（星号， 下划线），或者可以要求所有强调匹配第一个强调（一致）。
注意：为了防止像 like_this_one 这样包含内部下划线的单词产生不期望的强调，单词内的强调仅限于使用 asterisk。
理由：一致的格式使文档更易于理解。
MD050 - 强样式
标签: emphasis
别名：strong-style
参数：
style: 强样式 (string, 默认consistent, 值asterisk/consistent/underscore)
可修复：某些违规可以通过工具修复
这条规则在文档中使用的强调符号与配置的强调样式不匹配时被触发：
**Text**
__Text__
要修复此问题，请在整个文档中使用配置的强调样式：
**Text**
**Text**
配置的强调样式可以是一个特定的符号来使用（星号， 下划线），或者可以要求所有强调匹配第一个强调（一致）。
注意：单词内的强调仅限于使用下划线，以避免像__这样包含内部下划线的单词产生不期望的强调。
理由：一致的格式使文档更易于理解。
MD051 - 链接片段应为有效
标签：links
别名：link-fragments
参数：
ignore_case: 忽略片段的大小写（boolean，默认false）ignored_pattern: 忽略额外片段的模式（string，默认空字符串）
可修复：某些违规可以通过工具修复
当链接片段与文档中自动生成的标题片段不匹配时，此规则会被触发：
# Heading Name
[Link](#fragment)
要修复此问题，请将链接片段更改为引用现有标题的生成名称（见下文）：
# Heading Name
[Link](#heading-name)
为了保持一致性，本规则要求片段必须完全匹配将字母转换为小写的 GitHub 标题算法 。因此，以下示例被报告为违规：
# Heading Name
[Link](#Heading-Name)
在比较与标题名称的片段时忽略大小写，可以将 ignore_case 参数设置为 true。在此配置中，前面的示例不会报告为违规。
或者，某些平台允许在标题中使用语法 {#named-anchor} 来提供特定名称（仅包含小写字母、数字、- 和 _）：
# Heading Name {#custom-name}
[Link](#custom-name)
或者，任何带有 id 属性的 HTML 标签或带有 name 属性的 a 标签 attribute 可用于定义片段：
<a id="bookmark"></a>
[Link](#bookmark)
一个 a 标签在标题不适用或需要控制片段标识符文本的情况下很有用。
HTML 链接到 #top 滚动到文档顶部 。这条规则允许那种语法（使用小写以保持一致性）：
[Link](#top)
这条规则也识别 GitHub 用于突出显示文档中特定内容的自定义片段语法 特定内容 。
例如，这行第20行的链接：
[Link](#L20)
并且这个链接指向从第19行开始到第21行的内容：
[Link](#L19C5-L21C11)
一些 Markdown 生成器在构建文档时会动态创建并插入标题，例如通过组合一个固定的前缀如 figure- 和 递增数字计数器。要忽略此类生成的片段，请设置 ignored_pattern 正则表达式参数用于匹配一个模式（例如，^figure-）。
理由：GitHub 部分链接在 Markdown 内容在 GitHub 上显示时为每个标题自动创建。这使得直接链接到文档的不同部分变得容易。然而，如果标题被重命名或删除，部分链接会发生变化。这条规则有助于识别文档中损坏的部分链接。
部分链接不属于 CommonMark 规范。此规则强制执行 GitHub 标题算法 ，该算法为：将标题转换为小写，去除标点符号，将空格转换为连字符，根据需要附加递增的整数以确保唯一性。
MD052 - 参考链接和图片应使用已定义的标签
标签: images， links
别名: reference-links-images
参数：
ignored_labels: 忽略的链接标签 (string[]，默认["x"])shortcut_syntax: 包含快捷语法 (boolean, 默认false)
Markdown 中的链接和图片可以在使用时提供链接目标或图片来源，也可以在其他地方定义并使用标签进行引用。引用格式便于保持段落文本的整洁，并使在多个地方重用相同的 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
当对应的标签被定义时，链接或图片可以正确显示，但当标签不存在时，会以带括号的文本形式显示。默认情况下，此规则会警告"full"和"collapsed"引用语法中的未定义标签，但不会警告"shortcut"语法中的未定义标签，因为后者存在歧义。
文本 [example] 可能是一个快捷链接，或者是括号中的"example"文本，因此默认情况下会忽略"快捷"语法。要包含"快捷"语法，请将 include_shortcut 参数设置为 true。请注意，这样做会对文档中所有可能成为快捷链接的文本产生警告。如果括号中的文本是故意的，可以使用 \ 字符转义括号：\[example\]。
如果存在故意不引用的链接标签，可以通过将 ignored_labels 参数设置为要忽略的字符串列表来忽略它们。 此参数的默认值忽略复选框语法 GitHub 标准 Markdown 任务列表项 :
- [x] Checked task list item
MD053 - 链接和图片引用定义应该被需要
标签: images， links
别名： link-image-reference-definitions
参数：
ignored_definitions：忽略的定义（string[]，默认["//"]）
可修复：某些违规可以通过工具修复
Markdown 中的链接和图片可以在使用时提供链接目标或图片来源，也可以使用标签引用文档中其他位置的定义。后一种引用格式便于保持段落文本整洁，并使在多个地方重用相同的 URL 变得容易。
由于链接和图片引用的定义位于它们使用的地方之外，因此存在两种情况，其中定义可能是多余的：
- 如果一个标签在文档中没有被任何链接或图片引用，那么这个定义是未使用的，可以被删除。
- 如果一个标签在文档中定义了多次，那么第一个定义会被使用，其他的可以被删除。
这条规则认为，如果任何链接或图片引用有对应的标签，那么这个引用定义就是被使用的。"完整"、"折叠"和"快捷"格式都是支持的。
如果存在故意未引用的引用定义，可以通过将 ignored_definitions 参数设置为要忽略的字符串列表来忽略它们。此参数的默认值忽略了向 Markdown 添加非 HTML 注释的以下约定：
[//]: # (This behaves like a comment)
MD054 - 链接和图片样式
标签: images， links
别名：link-image-style
参数：
autolink: 允许自动链接 (boolean, 默认true)collapsed: 允许折叠的引用链接和图片 (boolean, 默认true)full: 允许完整引用链接和图片 (boolean, 默认true)inline: 允许内联链接和图片 (boolean, 默认true)shortcut: 允许快捷引用链接和图片 (boolean, 默认true)url_inline: 允许将 URL 作为内联链接使用（boolean，默认true）
可修复：某些违规可以通过工具修复
Markdown 中的链接和图片可以在使用时提供链接目标或图片来源，也可以使用标签引用文档中其他位置的定义。三种引用格式便于保持段落文本的整洁，并使在多个地方重用相同的 URL 变得容易。
默认情况下，此规则允许所有链接/图片样式。
将 autolink 参数设置为 false 将禁用自动链接：
<https://example.com>
将 inline 参数设置为 false 将禁用内联链接和图片：
[link](https://example.com)
将 full 参数设置为 false 将禁用完整引用链接和图片：
[link][url]
![image][url]
[url]: https://example.com
将 collapsed 参数设置为 false 将禁用折叠引用链接和图片：
[url][]
![url][]
[url]: https://example.com
将 shortcut 参数设置为 false 将禁用快捷引用链接和图片：
[url]
![url]
[url]: https://example.com
要修复此规则的违规，请将链接或图片更改为使用允许的样式。当链接或图片可以转换为 inline 样式（首选）时，此规则可以自动修复违规；或者当链接可以转换为... autolink 样式（不支持图片且必须为绝对 URL）。此规则不修复需要将链接或图片转换为 full、collapsed 或 shortcut 引用样式的情况，因为那需要命名引用并确定其在文档中的插入位置。
将 url_inline 参数设置为 false 可以防止使用具有相同绝对 URL 文本/目的地的无标题内联链接，因为此类链接可以转换为自动链接：
[https://example.com](https://example.com)
要修复 url_inline 违规，请改用更简单的自动链接语法：
<https://example.com>
理由：一致的格式使文档更易于理解。自动链接简洁，但显示为 URL，可能很长且令人困惑。内联链接和图片可以包含描述性文本，但在 Markdown 格式中占用更多空间。引用链接和图片在 Markdown 格式中更容易阅读和操作，但需要单独的链接引用定义。
MD055 - 表格管道风格
标签：table
别名：table-pipe-style
参数：
style：表格管道风格（string，默认值consistent，有效值consistent/leading_and_trailing/leading_only/no_leading_or_trailing/trailing_only)
这条规则在遇到 GitHub 标准 Markdown 表格 在首尾管道字符 (|) 使用上不一致时触发。
默认情况下 (consistent 样式)，文档中第一个表格的表头行用于确定应用于文档中所有表格的样式。也可以使用特定样式 (leading_and_trailing， leading_only， no_leading_or_trailing， trailing_only)。
此表格的表头行有首尾管道符，但其分隔行缺少尾部的管道符，并且其第一行单元格缺少首部的管道符：
| Header | Header |
| ------ | ------
Cell | Cell |
要修复这些问题，请确保每一行的开头和结尾都有一个管道字符：
| Header | Header |
| ------ | ------ |
| Cell | Cell |
请注意，紧随表格之后的文本（即不通过空行分隔）被视为表格的一部分（根据规范），也可能触发此规则：
| Header | Header |
| ------ | ------ |
| Cell | Cell |
This text is part of the table
理由：某些解析器在处理缺少开头或结尾管道字符的表格时存在困难。使用开头/结尾管道字符还可以帮助提供视觉清晰度。
MD056 - 表格列数
标签：table
别名：table-column-count
当 GitHub Flavored Markdown 表格 每一行的单元格数量不一致时，此规则将被触发。
这个表格的第二行数据单元格太少，而第三行数据单元格太多：
| Header | Header |
| ------ | ------ |
| Cell | Cell |
| Cell |
| Cell | Cell | Cell |
要修复这些问题，请确保每一行都有相同数量的单元格：
| Header | Header |
| ------ | ------ |
| Cell | Cell |
| Cell | Cell |
| Cell | Cell |
请注意，表格的表头行和分隔行必须有相同数量的单元格，否则它不会被识别为表格（根据规范）。
原因：行中的多余单元格通常不会显示，因此其数据会丢失。行中缺少单元格会在表格中形成空白，并暗示有遗漏。
MD058 - 表格应该被空行包围
标签：table
别名：blanks-around-tables
可修复：某些违规可以通过工具修复
当表格前后没有空行时，此规则会被触发：
Some text
| Header | Header |
| ------ | ------ |
| Cell | Cell |
> Blockquote
要修复此规则的违规，请确保所有表格在前后都有空行（除非表格位于文档的最开始或最末尾）：
Some text
| Header | Header |
| ------ | ------ |
| Cell | Cell |
> Blockquote
请注意，紧跟在表格后面的文本（即没有空行分隔的文本）被视为表格的一部分（根据规范），不会触发此规则：
| Header | Header |
| ------ | ------ |
| Cell | Cell |
This text is part of the table and the next line is blank
Some text
理由：除了美观原因外，某些解析器会错误地解析没有前后空行的表格。
MD059 - 链接文本应具有描述性
标签：accessibility， links
别名：descriptive-link-text
参数：
prohibited_texts: 禁止的链接文本 (string[], 默认["click here","here","link","more"])
当链接具有通用文本，如 [点击这里](...) 或 [链接](...) 时，将触发此规则。
链接文本应具有描述性，并传达链接的目的（例如， [Download the budget document](...) 或 [CommonMark Specification](...) ). 这对于屏幕阅读器尤其重要，因为屏幕阅读器有时会无上下文地呈现链接。
默认情况下，此规则禁止一些常见的英语单词/短语。要自定义这些单词/短语的列表，请将 prohibited_texts 参数设置为 Array 类型的 string。
注意：对于英语以外的语言，使用 prohibited_texts 参数来为该语言自定义列表。此规则的目标并非为每种语言提供翻译。
注意：此规则检查 Markdown 链接；HTML 链接将被忽略。
更多信息：https://webaim.org/techniques/hypertext/
以上就是目前的MarkdownLint定义清晰的规范格式，这段文本直接AI翻译的原文，不过我通读了一遍，没有大的问题，我并没有去修改，仅修改了少量的读起来很不通顺的句子，如果有错误请联系我修改，感谢。
总结
Markdown作为现代生活密不可分一的一部分，正逐渐以一种更加友好的方式走向大众，而不是少数开发者手里的精致小玩具。尤其是现代AI大模型广泛采用Markdown作为输出格式，未来的Markdown必将更加广泛，逐渐作为基本常识被大家所了解，学习。
这篇博客也是我打算用Markdown写技术文档时，回想起了之前VSCode的报错，突然感到好奇，然后去搜了搜，觉得不错，于是边学习边总结，写完了这篇博客。
我未来也打算认真遵循这些规范，并尝试学习更加高级的的Markdown语法，撰写更多的技术文档，学习笔记。也希望各位读者，也能喜欢上这个标记语言，并利用它对自己的学习工作做出改善！
参考文献：
你好！这里是 MARKDOWN 中文 | MARKDOWN 中文
Markdown 教程 - 中文官方文档 - Markdown文档网
Markdown - Wikipedia --- Markdown - Wikipedia
DavidAnson/markdownlint: A Node.js style checker and lint tool for Markdown/CommonMark files.
DavidAnson/vscode-markdownlint: Markdown linting and style checking for Visual Studio Code
