使用内容 linter

关于 GitHub Docs 内容 linter

我们的内容 linter 在我们的 Markdown 内容中强制执行风格指南规则。

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

运行 GitHub Docs 内容 linter

GitHub Docs 内容 linter 将在预提交时自动运行，但你也可以手动运行它。

在预提交时自动运行 linter

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

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

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

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

手动运行 linter

对暂存和已更改的文件运行 linter

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

npm run lint-content

对暂存和已更改的文件运行 linter，仅报告错误

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

npm run lint-content -- --errors

对特定文件或目录运行 linter

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

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

运行一组特定 linter 规则

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

对所有暂存和已更改的文件运行指定的 linter 规则

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

在特定文件或目录上运行指定的 linter 规则

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

绕过提交挂钩

如果 linter 捕获到您未引入的错误，您可以在提交更改时使用 --no-verify 选项绕过 git 提交挂钩。

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

显示内容 linter 脚本的帮助菜单

npm run lint-content -- --help

Linting 规则

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

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

语法用于 linting 规则

一些 linting 规则根据你可以添加到文章中的 HTML 注释返回警告或错误。

语法用于过期和已过期的内容

规则 GHD038 和 GHD039 检查手动指定了到期日期的内容。在指定日期前 14 天，内容 linter 将返回警告，表明内容即将过期。从指定日期开始，内容 linter 将返回错误并标记内容以进行修复。

你可以通过将内容包装在包含到期日期的 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 has been deprecated and will no longer be available after 28 June 2024.
</td>
</tr>
<!-- end expires 2024-06-28 -->

禁止 linter 规则

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

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

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

如果你要忽略的行在代码块中，你可以通过用以下注释将其包围来忽略代码块。

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

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