使用内容检查工具

关于 GitHub 文档内容检查工具

我们的内容检查工具在 Markdown 内容中强制执行风格指南规则。

检查工具使用 markdownlint 作为框架来执行检查、报告缺陷，并在可能的情况下自动修复内容。该框架灵活地运行特定规则，提供描述性的错误信息，并修复错误。GitHub 文档内容检查工具使用了多个现有的 markdownlint 规则以及额外的自定义规则来检查我们 content 和 data 目录中的 Markdown 内容。我们的自定义规则实现了在 markdownlint 框架中尚未提供或专属于 GitHub 文档内容的检查。规则同时检查 Markdown 和 Liquid 的语法。

运行 GitHub 文档内容检查工具

GitHub 文档内容检查工具会在 pre-commit 时自动运行，但您也可以手动运行它。

在 pre-commit 时自动运行检查工具

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

如果报告了任何错误，您的提交将不会完成。您需要修复报告的错误、重新添加已更改的文件，然后再次提交。如果报告了错误，必须修复这些错误，以防止内容出现违反 GitHub 文档风格指南的错误。若报告了警告，您可以选择修复或不修复。

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

如果您在 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 分支。大多数规则最终会升级为错误，一旦内容不再存在警告违规。

检查规则的语法

某些检查规则会根据您在文章中添加的 HTML 注释返回警告或错误。

过期和已过期内容的语法

规则 GHD038 和 GHD039 检查已手动设定过期日期的内容。在指定日期前 14 天，内容检查工具会返回警告，提示内容即将过期。从指定日期起，内容检查工具会返回警告并标记内容需整改。

您可以通过在内容外包裹包含过期日期的 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 -->

抑制检查规则

在极少数情况下，您可能需要记录违反一个或多个检查规则的内容。此时，您可以通过在 Markdown 文件中添加注释来抑制规则。您可以禁用所有规则或特定规则。尽量只禁用尽可能少的规则。您可以对整个文件、Markdown 文件的某个区段、特定行或下一行禁用规则。

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

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

如果您要忽略的行位于代码块中，您可以通过在代码块前后添加以下注释来忽略它。

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

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