Skip to main content

使用内容 Linter

可以使用内容 Linter 检查你贡献的内容是否存在任何错误。

“参与 GitHub Docs”部分中的文章指的是文档本身,是 GitHub 员工和开放源代码参与者的资源。

关于 GitHub Docs 内容 Linter

内容 Linter 在 Markdown 内容中强制实施风格指南规则。

Linter 使用 markdownlint 作为框架来执行检查、报告缺陷并尽可能自动修复内容。 此框架可灵活运行特定规则、提供描述性错误消息并修复错误。 GitHub Docs 内容 Linter 使用多个现有 markdownlint 规则和其他自定义规则来检查 contentdata 目录中的 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。 它将输出 warningerror 严重性缺陷。

npm run lint-content

对暂存和更改的文件运行 Linter,并且仅报告错误

使用以下命令在暂存和更改的文件上本地运行 Linter,并仅报告 error 严重性缺陷。

npm run lint-content -- --errors

在特定文件或目录上运行 Linter

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

Shell
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-incrementcode-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规则名称说明严重性标记
MD001heading-increment、header-increment标题级别一次只能递增一个级别errorheadings、headers
MD002first-heading-h1、first-header-h1第一个标题应该是顶级标题errorheadings、headers
MD004ul-style无序列表样式errorbullet、ul
MD009no-trailing-spaces尾随空格error空格
MD011no-reversed-links反向链接语法error链路
MD012no-multiple-blanks多个连续空白行errorwhitespace、blank_lines
MD014commands-show-output如果不显示输出,则在命令之前使用美元符号errorcode
MD018no-missing-space-atxAtx 样式标题上的哈希后没有空格errorheadings、headers、atx、spaces
MD019no-multiple-space-atxAtx 样式标题上的哈希后多个空格errorheadings、headers、atx、spaces
MD022blanks-around-headings、blanks-around-headers标题前后应该都留有空白行errorheadings、headers、blank_lines
MD023heading-start-left、header-start-left标题必须以行首开头errorheadings、headers、spaces
MD027no-multiple-space-blockquote块引号符号后多个空格errorblockquote、whitespace、indentation
MD029ol-prefix已排序列表项前缀errorol
MD030list-marker-space列表标记后空格errorol、ul、whitespace
MD031blanks-around-fences隔离代码块前后应该都留有空白行errorcode、blank_lines
MD037no-space-in-emphasis强调标记内空格errorwhitespace、emphasis
MD039no-space-in-links链接文本内空格errorwhitespace、links
MD040fenced-code-language隔离代码块应指定语言errorcode、language
MD042no-empty-links无空链接error链路
MD047single-trailing-newline文件应以单个换行符结尾errorblank_lines
MD049emphasis-style强调样式应一致erroremphasis
MD050strong-style强样式应一致erroremphasis
search-replacetodocs-placeholder捕获 TODOCS 占位符的出现次数。error
search-replacedocs-domain捕获 docs.gitub.com 域的出现次数。warning
search-replacehelp-domain捕获 help.github.com 域的出现次数。error
search-replacepreview-domain捕获 preview.ghdocs.com 域的出现次数。error
search-replacedeveloper-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
GH001no-default-alt-text图像应具有有意义的备用文本(替换文本)erroraccessibility、images
GH002no-generic-link-text避免使用通用链接文本,例如 Learn moreClick hereerroraccessibility、links
GHD030code-fence-line-length代码隔离行不应超过最大长度warningcode、accessibility
GHD032image-alt-text-end-punctuation图像的替换文本应以标点符号结尾erroraccessibility、images
GHD004image-file-kebab-case图像文件名必须使用 kebab-case 命名法errorimages
GHD033incorrect-alt-text-length图像替换文本应介于 40-150 个字符之间warningaccessibility、images
GHD002internal-links-no-lang内部链接不得有硬编码的语言代码errorlinks、url
GHD003internal-links-slash内部链接必须以 / 开头errorlinks、url
GHD031image-alt-text-exclude-words图像的替换文本不应以“image”或“graphic”等单词开头erroraccessibility、images
GHD034list-first-word-capitalization列表项的第一个单词应大写warningul、ol
GHD001link-punctuation内部链接标题不得包含标点符号errorlinks、url
GHD008early-access-references未提前访问的文件不应引用 early-access 或 early-access 文件errorfeature、early-access
GHD021yaml-scheduled-jobs包含计划工作流的 YAML 片段不得整点运行,且必须是唯一的errorfeature、actions
GHD006internal-links-old-version内部链接不得具有使用旧版本控制语法的硬编码版本errorlinks、url、versioning
GHD005hardcoded-data-variable包含“个人访问令牌”的字符串应改用产品变量errorsingle-source
GHD013github-owned-action-references不应硬编码 GitHub 拥有的操作引用errorfeature、actions
GHD016liquid-quoted-conditional-argLiquid 条件标记不应引用条件自变量errorliquid、format
GHD014liquid-data-references-defined在内容中找到的 liquid 数据或缩进数据引用,这些数据没有值或在数据目录中不存在errorliquid
GHD015liquid-data-tag-formatLiquid 数据或缩进数据引用标记必须具有正确的自变量数量和间距errorliquid、format
GHD010frontmatter-hidden-docs具有前辅文属性 hidden 的文章只能位于特定产品中errorfrontmatter、feature、early-access
GHD009frontmatter-early-access-references未提前访问的文件不应具有引用 early-access 的前辅文errorfrontmatter、feature、early-access
GH011frontmatter-video-transcripts必须正确配置视频脚本errorfrontmatter、feature、video-transcripts
GHD012frontmatter-schema前辅文必须符合架构errorfrontmatter、schema
GHD007code-annotationsMarkdown 中定义的代码注释必须包含特定的布局前辅文属性errorcode、feature、annotate、frontmatter
GHD017frontmatter-liquid-syntax前辅文属性必须使用有效的 Liquiderrorliquid、frontmatter
GHD018liquid-syntaxMarkdown 内容必须使用有效的 Liquiderrorliquid
GHD019liquid-if-tags在自变量为有效版本时,应使用 liquid ifversion 标记而不是 if 标记errorliquid、versioning
GHD020liquid-ifversion-tagsLiquid ifversion 标记应包含有效的版本名称作为自变量errorliquid、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 -->
按名称禁用下一行的一条或多条规则