CI配置说明文档

配置文件名称	作用
config.json	总配置文件
markdownlint.config.json	markdown语法检查配置
url.whitelist.json	链接白名单配置

1. config.json

总配置文件

{
  "name": "xxx 文档检查配置", // 可选，配置文件名称
  "config": { // 模板配置，在此定义的配置在每个仓库继承
    // ...
  },
  "repo": { // 仓库配置，存放仓库的配置信息，可根据仓库覆盖config字段的配置
    // ...
  }
}

1.1 具体字段说明

1.1.1 config

config 是一个对象，存放模板的配置信息，key 为模板名称，value 为模板的配置信息

• docPath: 必需字段，string，文档路径，正则表达式，匹配到的文件将进行文档检查
• markdownlintRemoteConfigUrl: 非必需字段，string，markdownlint 配置文件地址，可以是本地文件路径，也可以是网络文件路径
• codespellCheckRemoteWhitelistUrl: 非必需字段，string，codespell-check的单词白名单配置文件地址，可以是本地文件路径，也可以是网络文件路径
• linkValidityCheckRemoteWhitelistUrl: 非必需字段，string，link-validity-check 白名单配置文件地址，可以是本地文件路径，也可以是网络文件路径
• linkValidityCheckDisableExternalUrl: 非必需字段，boolean，默认 false，link-validity-check 禁用外部链接检查
• linkValidityCheckDisableInternalUrl: 非必需字段，boolean，默认 false，link-validity-check 禁用内部链接检查
• linkValidityCheckDisableAnchor: 非必需字段，boolean，默认 false，link-validity-check 禁用锚点检查
• linkValidityCheckDisableOnly404Status: 非必需字段，boolean，默认 false，link-validity-check 禁用仅检查 404 链接，禁用意味着将检查额外异常状态的链接，会增加误报
• resourceExistenceCheckRemoteWhitelistUrl: 非必需字段，string，resource-existence-check 白名单配置文件地址，可以是本地文件路径，也可以是网络文件路径
• resourceExistenceCheckDisableExternalUrl: 非必需字段，boolean，默认 false，resource-existence-check 禁用外部链接检查
• resourceExistenceCheckDisableInternalUrl: 非必需字段，boolean，默认 false，resource-existence-check 禁用内部链接检查
• resourceExistenceCheckDisableOnly404Status: 非必需字段，boolean，默认 false，resource-existence-check 禁用仅检查 404 资源，禁用意味着将检查额外异常状态的资源，会增加误报
• tocCheckDisableMdInToc: 非必需字段，boolean，默认 false，toc-check 禁用 markdown 文件是否加入toc检查
• ci: 必需字段，启用的 CI 检测，支持如下 CI：
  • markdownlint: Markdown 语法检查
  • tag-closed-check: Html 标签闭合检查
  • link-validity-check: 链接有效性检查（包含：1. 内链；2. 外链；3.锚点）
  • resource-existence-check: 资源有效性检查（包含：1. 内链；2. 外链）
  • toc-check: Toc 检查（1. _toc.yaml语法是否正确_；2. 每一篇 md 文档都需要在目录中进行维护）
  • codespell-check: 单词拼写检查
  • file-naming-check: 目录和文件是否符合命名规范检查（小写字母，下划线连接）
  • file-naming-consistency-check: Markdown 中英文文档名称是否一致检查

如下：

{
  "name": "xxx 文档检查配置",
  "config": {
    "base": {
      "docPath": ".*",
      "markdownlintRemoteConfigUrl": "https://raw.gitcode.com/openeuler/docs/raw/stable-common/.doctools/markdownlint.config.json",
      "codespellCheckRemoteWhitelistUrl": "https://raw.gitcode.com/openeuler/docs/raw/stable-common/.doctools/codespell.whitelist.txt",
      "linkValidityCheckRemoteWhitelistUrl": "https://raw.gitcode.com/openeuler/docs/raw/stable-common/.doctools/url.whitelist.txt",
      "resourceExistenceCheckRemoteWhitelistUrl": "https://raw.gitcode.com/openeuler/docs/raw/stable-common/.doctools/url.whitelist.txt",
      "linkValidityCheckDisableExternalUrl": false,
      "linkValidityCheckDisableInternalUrl": false,
      "linkValidityCheckDisableAnchor": false,
      "linkValidityCheckDisableOnly404Status": false,
      "resourceExistenceCheckDisableExternalUrl": false,
      "resourceExistenceCheckDisableInternalUrl": false,
      "resourceExistenceCheckDisableOnly404Status": false,
      "tocCheckDisableMdInToc": false,
      "ci": [
        "markdownlint",
        "tag-closed-check",
        "link-validity-check",
        "resource-existence-check",
        "toc-check",
        "codespell-check",
        "file-naming-check",
        "file-naming-consistency-check"
      ]
    }
  },
  "repo": {
    // ...
  }
}

1.1.2 repo

repo 是一个对象，存放仓库的具体配置信息，key 为仓库名称（owner/name的形式，如果匹配所有仓库请填写 all），value 为仓库的配置信息

如：对于 https://gitcode.com/openeuler/docs 仓库，其 key 为 openeuler/docs

• extendConfig: 非必需字段，继承的模板名称，取值为 config 中定义的模板名称
• 其它字段：参考 1.1.1 config，在仓库配置中定义后将覆盖模板中的字段
• branches: 非必需字段，仓库的分支配置，对分支使用自定义配置进行检查；key 为分支名称，value 为分支的配置信息
  • branches字段说明：
    • extendConfig: 非必需字段，继承的模板名称，取值为 config 中定义的模板名称，如果缺失该字段，则使用仓库配置
    • 覆盖字段：参考 1.1.1 config 说明，在仓库配置中定义后将覆盖模板中的字段

如下：

{
  "name": "xxx 文档检查配置",
  "config": {
    "base": {
      "docPath": ".*",
      "linkValidityCheckDisableExternalUrl": false,
      "linkValidityCheckDisableInternalUrl": false,
      "linkValidityCheckDisableAnchor": false,
      "linkValidityCheckDisableOnly404Status": false,
      // ...
    }
  },
  "repo": {
    "openeuler/docs": {
      "extendConfig": "base",
      "linkValidityCheckDisableExternalUrl": true,
      "branches": {
        "master": {
          "linkValidityCheckDisableOnly404Status": true,
          "ci": [
            "markdownlint",
            "tag-closed-check",
            "link-validity-check",
            "resource-existence-check",
            "toc-check",
            "codespell-check",
            "file-naming-consistency-check"
          ]
        },
        "stable-25.03": {
          "ci": [
            "markdownlint",
            "tag-closed-check",
            "link-validity-check",
            "resource-existence-check",
            "toc-check",
            "codespell-check"
          ]
        }
      }
    }
  }
}

2. markdownlint.config.json

markdownlint 配置文件是一个 JSON 对象，相关的规则请查阅：https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/md001.md

默认情况下开启所有规则（即 default 设置为 true），若要关闭某个规则，将规则值设置为 false 即可

{
  "default": true,
  "MD003": {
    "style": "atx"
  },
  "MD029": {
    "style": "ordered"
  },
  "MD004": false,
  "MD007": false,
  "MD009": false,
  "MD013": false,
  "MD014": false,
  "MD020": false,
  "MD021": false,
  "MD024": false,
  "MD025": false,
  "MD033": false,
  "MD036": false,
  "MD042": false,
  "MD043": false,
  "MD044": false,
  "MD045": false,
  "MD046": false,
  "MD048": false,
  "MD049": false,
  "MD050": false,
  "MD051": false,
  "MD052": false,
  "MD053": false,
  "MD055": false,
  "MD056": false,
  "MD057": false
}

3. url.whitelist.json

url.whitelist.txt 是一个 JSON 文件，存放白名单的链接，支持正则匹配

[
  "^(mailto:|file://|ftp://).*",
  "^(https?://)?localhost.*"
]

4. codespell.whitelist.json

codespell.whitelist.txt 是一个 JSON 文件，存放白名单的单词

[
  "GLIBCXX",
  "rcfile",
  "noprofile"
]