使用内容 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 将自动对这些暂存文件进行 Lint 分析。 同时报告警告和错误，但只有错误会阻止提交完成。

如果报告了任何错误，则不会完成提交。 你需要修复报告的错误、重新添加已更改的文件，然后再次提交更改。 必须修复报告的任何错误，以防止在内容中引入违反 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

Lint 分析规则

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

必须先解决错误，然后才能将更改合并到 main 分支。 应解决警告，但不阻止将更改合并到 main 分支中。 一旦内容不再出现警告冲突，大多数规则最终将提升为错误。

Lint 分析规则的语法

某些 Lint 分析规则会根据可以添加到文章中的 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 is 弃用 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 -->

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