关于 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 分支中。 一旦内容不再出现警告冲突，大多数规则最终将提升为错误。
| 规则 ID | 规则名称 | 说明 | 严重性 | 标记 |
|---|---|---|---|---|
| MD001 | heading-increment、header-increment | 标题级别一次只能递增一个级别 | error | headings、headers |
| MD002 | first-heading-h1、first-header-h1 | 第一个标题应该是顶级标题 | error | headings、headers |
| MD004 | ul-style | 无序列表样式 | error | bullet、ul |
| MD009 | no-trailing-spaces | 尾随空格 | error | 空格 |
| MD011 | no-reversed-links | 反向链接语法 | error | 链路 |
| MD012 | no-multiple-blanks | 多个连续空白行 | error | whitespace、blank_lines |
| MD014 | commands-show-output | 如果不显示输出，则在命令之前使用美元符号 | error | code |
| MD018 | no-missing-space-atx | Atx 样式标题上的哈希后没有空格 | error | headings、headers、atx、spaces |
| MD019 | no-multiple-space-atx | Atx 样式标题上的哈希后多个空格 | error | headings、headers、atx、spaces |
| MD022 | blanks-around-headings、blanks-around-headers | 标题前后应该都留有空白行 | error | headings、headers、blank_lines |
| MD023 | heading-start-left、header-start-left | 标题必须以行首开头 | error | headings、headers、spaces |
| MD027 | no-multiple-space-blockquote | 块引号符号后多个空格 | error | blockquote、whitespace、indentation |
| MD029 | ol-prefix | 已排序列表项前缀 | error | ol |
| MD030 | list-marker-space | 列表标记后空格 | error | ol、ul、whitespace |
| MD031 | blanks-around-fences | 隔离代码块前后应该都留有空白行 | error | code、blank_lines |
| MD037 | no-space-in-emphasis | 强调标记内空格 | error | whitespace、emphasis |
| MD039 | no-space-in-links | 链接文本内空格 | error | whitespace、links |
| MD040 | fenced-code-language | 隔离代码块应指定语言 | error | code、language |
| MD042 | no-empty-links | 无空链接 | error | 链路 |
| MD047 | single-trailing-newline | 文件应以单个换行符结尾 | error | blank_lines |
| MD049 | emphasis-style | 强调样式应一致 | error | emphasis |
| MD050 | strong-style | 强样式应一致 | error | emphasis |
| search-replace | todocs-placeholder | 捕获 TODOCS 占位符的出现次数。 | error | |
| search-replace | docs-domain | 捕获 docs.gitub.com 域的出现次数。 | warning | |
| search-replace | help-domain | 捕获 help.github.com 域的出现次数。 | error | |
| search-replace | preview-domain | 捕获 preview.ghdocs.com 域的出现次数。 | error | |
| search-replace | developer-domain | 捕获 developer.github.com 域的出现次数。 | error | |
| search-replace | 弃用的 liquid 语法：site.data | 捕获弃用的 liquid 数据语法的出现次数。 | error | |
| search-replace | 弃用的 liquid 语法：octicon- | 使用的八进制 liquid 语法已弃用。 请改用此格式 octicon "<octicon-name>" aria-label="<Octicon aria label>" | error | |
| GH001 | no-default-alt-text | 图像应具有有意义的备用文本（替换文本） | error | accessibility、images |
| GH002 | no-generic-link-text | 避免使用通用链接文本，例如 Learn more 或 Click here | error | accessibility、links |
| GHD030 | code-fence-line-length | 代码隔离行不应超过最大长度 | warning | code、accessibility |
| GHD032 | image-alt-text-end-punctuation | 图像的替换文本应以标点符号结尾 | error | accessibility、images |
| GHD004 | image-file-kebab-case | 图像文件名必须使用 kebab-case 命名法 | error | images |
| GHD033 | incorrect-alt-text-length | 图像替换文本应介于 40-150 个字符之间 | warning | accessibility、images |
| GHD002 | internal-links-no-lang | 内部链接不得有硬编码的语言代码 | error | links、url |
| GHD003 | internal-links-slash | 内部链接必须以 / 开头 | error | links、url |
| GHD031 | image-alt-text-exclude-words | 图像的替换文本不应以“image”或“graphic”等单词开头 | error | accessibility、images |
| GHD034 | list-first-word-capitalization | 列表项的第一个单词应大写 | warning | ul、ol |
| GHD001 | link-punctuation | 内部链接标题不得包含标点符号 | error | links、url |
| GHD008 | early-access-references | 未提前访问的文件不应引用 early-access 或 early-access 文件 | error | feature、early-access |
| GHD021 | yaml-scheduled-jobs | 包含计划工作流的 YAML 片段不得整点运行，且必须是唯一的 | error | feature、actions |
| GHD006 | internal-links-old-version | 内部链接不得具有使用旧版本控制语法的硬编码版本 | error | links、url、versioning |
| GHD005 | hardcoded-data-variable | 包含“个人访问令牌”的字符串应改用产品变量 | error | single-source |
| GHD013 | github-owned-action-references | 不应硬编码 GitHub 拥有的操作引用 | error | feature、actions |
| GHD016 | liquid-quoted-conditional-arg | Liquid 条件标记不应引用条件自变量 | error | liquid、format |
| GHD014 | liquid-data-references-defined | 在内容中找到的 liquid 数据或缩进数据引用，这些数据没有值或在数据目录中不存在 | error | liquid |
| GHD015 | liquid-data-tag-format | Liquid 数据或缩进数据引用标记必须具有正确的自变量数量和间距 | error | liquid、format |
| GHD010 | frontmatter-hidden-docs | 具有前辅文属性 hidden 的文章只能位于特定产品中 | error | frontmatter、feature、early-access |
| GHD009 | frontmatter-early-access-references | 未提前访问的文件不应具有引用 early-access 的前辅文 | error | frontmatter、feature、early-access |
| GH011 | frontmatter-video-transcripts | 必须正确配置视频脚本 | error | frontmatter、feature、video-transcripts |
| GHD012 | frontmatter-schema | 前辅文必须符合架构 | error | frontmatter、schema |
| GHD007 | code-annotations | Markdown 中定义的代码注释必须包含特定的布局前辅文属性 | error | code、feature、annotate、frontmatter |
| GHD017 | frontmatter-liquid-syntax | 前辅文属性必须使用有效的 Liquid | error | liquid、frontmatter |
| GHD018 | liquid-syntax | Markdown 内容必须使用有效的 Liquid | error | liquid |
| GHD019 | liquid-if-tags | 在自变量为有效版本时，应使用 liquid ifversion 标记而不是 if 标记 | error | liquid、versioning |
| GHD020 | liquid-ifversion-tags | Liquid ifversion 标记应包含有效的版本名称作为自变量 | error | liquid、versioning |
抑制 Linter 规则
极少数情况下，可能需要记录违反一条或多条 Linter 规则的内容。 在这些情况下，可以通过向 Markdown 文件添加注释来抑制规则。 可以禁用所有规则或特定规则。 始终尽可能少地限制规则。 可以为整个文件、Markdown 文件的某一部分、特定行或下一行禁用规则。
例如，如果要编写包含检查反向链接语法的正则表达式 (^|/)[Cc]+odespace/ 的文章，则会触发检查反向链接的 MD011 规则。 可以通过添加以下注释来禁用该特定行上的规则 MD011。
(^|/)[Cc]+odespace/ <!-- markdownlint-disable-line MD011 -->
如果尝试忽略的行在代码块中，可以通过将代码块与以下注释围绕它来忽略代码块。
<!-- markdownlint-disable MD011 --> ``` (^|/)[Cc]+odespace/ ``` <!-- markdownlint-enable MD011 -->
可以使用这些注释来启用或禁用规则。
| 注释 | 效果 |
|---|---|
<!-- markdownlint-disable --> | 禁用所有规则 |
<!-- markdownlint-enable --> | 启用所有规则 |
<!-- markdownlint-disable-line --> | 禁用当前行的所有规则 |
<!-- markdownlint-disable-next-line --> | 禁用下一行的所有规则 |
<!-- markdownlint-disable RULE-ONE RULE-TWO --> | 按名称禁用一条或多条规则 |
<!-- markdownlint-enable RULE-ONE RULE-TWO --> | 按名称启用一条或多条规则 |
<!-- markdownlint-disable-line RULE-NAME --> | 按名称禁用当前行的一条或多条规则 |
<!-- markdownlint-disable-next-line RULE-NAME --> | 按名称禁用下一行的一条或多条规则 |