使用内容代码检查器

关于 GitHub Docs 内容代码检查器

我们的内容代码检查器会在我们的 Markdown 内容中强制执行样式指南规则。

代码检查器使用 markdownlint 作为执行检查、报告缺陷并在可能的情况下自动修复内容的框架。此框架可以灵活地运行特定规则，提供描述性错误消息并修复错误。GitHub Docs 内容代码检查器使用一些现有的 markdownlint 规则和一些额外的自定义规则来检查我们 content 和 data 目录中的 Markdown 内容。我们的自定义规则实现了尚未在 markdownlint 框架中提供的检查，或者特定于 GitHub Docs 内容的检查。规则会检查 Markdown 和 Liquid 的语法。

运行 GitHub Docs 内容代码检查器

GitHub Docs 内容代码检查器将在预提交时自动运行，但您也可以手动运行它。

在预提交时自动运行代码检查器

当您在本地编写内容并使用命令行提交文件时，这些暂存的文件将由内容代码检查器自动进行代码检查。将报告警告和错误，但只有错误才会阻止您的提交完成。

如果报告了任何错误，您的提交将无法完成。您需要修复报告的错误，重新添加已更改的文件，然后再次提交更改。必须修复报告的任何错误，以防止在内容中引入违反 GitHub Docs 样式指南的错误。如果报告了任何警告，您可以选择修复或不修复它们。

当您在本地编写内容时，您可以使用命令行自动修复一些规则。如果您想自动修复可以修复的错误，请参阅“自动修复可以修复的错误”。

如果您在 GitHub UI 中编辑文件，则无法自动修复错误或在提交时运行代码检查器，但如果内容违反了任何严重性为 error 的规则，则会收到 CI 失败。

手动运行代码检查器

在暂存和已更改的文件上运行代码检查器

使用以下命令在本地对暂存和已更改的文件运行代码检查器。它将输出 warning 和 error 严重性缺陷。

npm run lint-content

在暂存和已更改的文件上运行代码检查器，仅报告错误

使用以下命令在本地对暂存和已更改的文件运行代码检查器，并仅报告 error 严重性缺陷。

npm run lint-content -- --errors

在特定文件或目录上运行代码检查器

使用以下命令在本地对特定文件或目录运行代码检查器。用空格分隔多个路径。您可以在同一命令中包含文件和目录。

npm run lint-content -- \
  --paths content/FILENAME.md content/DIRECTORY

npm run lint-content -- \
  --paths content/FILENAME.md content/DIRECTORY

自动修复可以修复的错误

如果错误在其描述中包含 fixable: true，则可以使用以下命令自动修复它们。

运行此命令仅修复暂存和已更改的文件

npm run lint-content -- --fix

运行此命令修复特定文件或目录

npm run lint-content -- \
  --fix --paths content/FILENAME.md content/DIRECTORY

运行一组特定的代码检查规则

使用以下命令运行一个或多个特定的代码检查规则。这些示例运行 heading-increment 和 code-fence-line-length 规则。将 heading-increment code-fence-line-length 替换为您想要运行的一个或多个代码检查器别名。若要查看可以传递给此选项的代码检查规则列表，请运行 npm run lint-content -- --help。您可以使用代码检查规则的短名称（例如，MD001）或长名称（例如，heading-increment）。

在所有暂存和已更改的文件上运行指定的代码检查规则

npm run lint-content -- \
  --rules heading-increment code-fence-line-length

在特定文件或目录上运行指定的代码检查规则

npm run lint-content -- \
  --rules heading-increment code-fence-line-length \
  --path content/FILENAME.md content/DIRECTORY

绕过提交钩子

如果代码检查器捕获了您未引入的错误，则可以在提交更改时使用 --no-verify 选项绕过 git 提交钩子。

git commit -m 'MESSAGE' --no-verify

显示内容代码检查器脚本的帮助菜单

npm run lint-content -- --help

代码检查规则

每个规则都配置在 src/content-linter/style 中的文件中，规则的严重性是在此处定义的。

必须在将您的更改合并到 main 分支之前解决错误。应解决警告，但不会阻止更改合并到 main 分支。大多数规则最终将升级为错误，一旦内容不再有警告违规。

Lint 规则的语法

某些 Lint 规则会根据您可以添加到文章中的 HTML 注释返回警告或错误。

即将过期和已过期内容的语法

规则 GHD038 和 GHD039 检查手动指定过期日期的内容。在指定日期之前的十四天，内容 Lint 程序将返回一条警告，提示内容即将过期。从指定日期开始，内容 Lint 程序将返回错误并标记内容以进行修复。

您可以通过将其包装在包含以下格式的过期日期的 HTML 标签中，将过期日期添加到内容中：<!-- expires yyyy-mm-dd --> <!-- end expires yyyy-mm-dd -->

使用

This content does not expire.
<!-- expires 2022-01-28 -->
This content expires on January 28, 2022.
<!-- end expires 2022-01-28 -->
This content also does not expire.

请注意，如果将过期标签放在 HTML table 元素中，请确保标签围绕整个行，而不仅仅是单元格。例如

<!-- expires 2024-06-28 -->
<tr>
<td>
macOS
</td>
<td>
The <code>macos-11</code> label is closing down and will no longer be available after 28 June 2024.
</td>
</tr>
<!-- end expires 2024-06-28 -->

禁用 Lint 规则

在极少数情况下，您可能需要记录违反一个或多个 Lint 规则的内容。在这些情况下，您可以通过向 Markdown 文件添加注释来禁用规则。您可以禁用所有规则或特定规则。始终尝试限制尽可能少的规则。您可以为整个文件、Markdown 文件的一部分、特定行或下一行禁用规则。

例如，如果您正在编写一篇包含正则表达式 (^|/)[Cc]+odespace/ 的文章，该表达式检查反向链接语法，它将触发检查反向链接的 MD011 规则。您可以通过添加以下注释来禁用该特定行的 MD011 规则。

(^|/)[Cc]+odespace/ <!-- markdownlint-disable-line MD011 -->

如果要忽略的行位于代码块中，则可以通过以下注释将其括起来以忽略代码块。

<!-- markdownlint-disable MD011 -->
```
(^|/)[Cc]+odespace/
```
<!-- markdownlint-enable MD011 -->

您可以使用这些注释启用或禁用规则。