markdownlint 文档测试

markdownlint 会检查 Markdown 语法是否遵循 特定规则，并且被 docs-lint 测试使用。

我们的 文档风格指南 和 Markdown 指南 详细说明了为 GitLab 文档选择 Markdown 语法时必须做出的选择。 此工具有助于捕获偏离这些指南的情况。

markdownlint 配置可在以下项目中找到：

• gitlab
• gitlab-runner
• omnibus-gitlab
• charts
• gitlab-development-kit
• gitlab-operator

此配置也用于构建管道中。

您可以使用 markdownlint：

• 在命令行上，使用以下任一工具：
  • markdownlint-cli。
  • markdownlint-cli2。
• 在代码编辑器中。
• 在 pre-push 钩子中。

安装 markdownlint

您可以安装 markdownlint-cli 或 markdownlint-cli2 来运行 markdownlint。

要安装 markdownlint-cli，请运行：

yarn global add markdownlint-cli

要安装 markdownlint-cli2，请运行：

yarn global add markdownlint-cli2

您应该安装与 GitLab Docs 项目中使用的版本相匹配的 markdownlint-cli 或 markdownlint-cli2 版本。 您可以在 variables: 部分 中找到正确的版本。

在您的编辑器中配置 markdownlint

在编辑器中使用 markdownlint 比必须从命令行运行命令更方便。

要在您的编辑器中配置 markdownlint，请适当安装以下之一：

• Visual Studio Code DavidAnson.vscode-markdownlint 扩展。

• Sublime Text SublimeLinter-contrib-markdownlint 包。 此包默认使用 markdownlint-cli，但可以通过以下 SublimeLinter 配置使用 markdownlint-cli2：

  "markdownlint": {
    "executable": [ "markdownlint-cli2" ]
  }

• Vim ALE 插件。

• Emacs Flycheck 扩展。Flycheck 支持 markdownlint-cli 开箱即用，但您必须添加一个 .dir-locals.el 文件来 指向项目目录基础处的 .markdownlint.yml：

  ;; 将此代码放在 gitlab 项目根目录中名为 `.dir-locals.el` 的文件中。
  ((markdown-mode . ((flycheck-markdown-markdownlint-cli-config . ".markdownlint.yml"))))

在本地运行 markdownlint-cli2

您可以在存储库中的任何位置运行 markdownlint-cli2。从存储库的根目录， 您无需指定配置文件的位置。如果您从存储库的其他位置运行它， 您必须指定配置文件的位置。在这些命令中， 将 doc/**/*.md 替换为存储库中 Markdown 文件的路径：

# 从根目录运行时，无需指定配置文件
$ markdownlint-cli2 'doc/**/*.md'

# 从存储库的其他位置运行时，指定配置文件
$ markdownlint-cli2 --config .markdownlint-cli2.yaml 'doc/**/*.md'

有关命令行选项的完整列表，请参阅 markdownlint-cli2 文档中的 命令行。

禁用 markdownlint 测试

要禁用所有 markdownlint 规则，请在文本前添加 <!-- markdownlint-disable --> 标签， 在文本后添加 <!-- markdownlint-enable --> 标签。

要仅禁用 特定规则， 请将规则编号添加到标签中，例如 <!-- markdownlint-disable MD044 --> 和 <!-- markdownlint-enable MD044 -->。

尽可能只排除有问题的行。

故障排除

Markdown 规则 MD044/proper-names（大小写）

一个可能引起混淆的规则是 MD044/proper-names。失败情况， 或如何纠正它，可能不会立即清楚。 此规则检查每个项目中 .markdownlint.yml 文件中列出的已知单词列表， 以验证大小写和反引号的使用。反引号中的单词会被 markdownlint 忽略。

通常，产品名称应遵循产品、协议等的官方名称的确切大小写。

如果使用错误的大小写，一些示例会失败：

• MinIO（需要大写的 IO）
• NGINX（需要全部大写）
• runit（需要小写的 r）

此外，命令、参数、值、文件名等必须包含在反引号中。例如：

• “在您的 .gitlab-ci.yml 中更改 needs 关键字…”
  • needs 是一个参数，.gitlab-ci.yml 是一个文件，所以两者都需要反引号。 此外，没有反引号的 .gitlab-ci.yml 会通过 markdownlint 失败，因为它 没有大写的 G 或 L。
• “运行 git clone 来克隆 Git 仓库…”
  • git clone 是一个命令，所以它必须是小写，而 Git 是产品， 所以它必须有大写的 G。