1. 授权认证
  2. 获取用户个人信息
  3. 项目协同
  4. 代码托管
  5. 持续集成
  6. 制品仓库
  7. 测试管理
  1. 项目协同
  2. 代码仓库
  3. DevOps 实践之旅
  4. 一分钟开始持续集成之旅
  5. 持续部署
  6. 制品库

Markdown 代码规范

Markdown 常用代码规范检查工具如下:

工具 用途 lint 命令 支持 IDE
remark Markdown 通用规范 remark -f docs/ VSCode
lint-md Markdown 中文规范 lint-md docs/ VSCode
fnlint 文件名 slug 规范 fnlint -c .fnlint.json 不支持

remark

remark 是国际流行的开源项目,用于检查 Markdown 书写规范,内置推荐规范「remark-preset-lint-recommended」,常见规则如下:

  • 文本文件结尾需要换行符(POSIX 规范);
  • 列表:顶格,符号后 3 个空格;

安装:

$ npm install -save-dev remark-cli remark-preset-lint-recommended
$ vi package.json
  "scripts": {
    "lint-all": "remark -f docs/"
  },
  "remarkConfig": {
    "plugins": ["remark-preset-lint-recommended"]
  }

全量检查:

$ npx remark -f docs/
docs/start/ci.md: no issues found
docs/open/start.md
     1:1   warning  Missing newline character at end of file
     16:4  warning  Incorrect list-item indent: add 1 space
     22:3  warning  Incorrect list-item indent: add 2 spaces
⚠ 2422 warnings

本地增量检查:

git diff --diff-filter=d --name-only HEAD | grep ".md$" | xargs npx remark -f

持续集成合并请求增量检查:

sh "git diff --diff-filter=d --name-only ${env.MR_TARGET_BRANCH}... | grep '.md\$' | xargs npx remark -f"

lint-md

lint-md 用于检查 Markdown 中文书写规范,内置「阮一峰中文技术文档规范」,常见规则如下:

  • 中文与英文之间需要空格
  • 中文与数字之间需要空格
  • 代码块需声明编程语言
  • 禁止使用全角数字

安装:

$ npm install -save-dev lint-md-cli

全量检查:

$ lint-md docs/
docs/project/open/webhook.md
51:1-51:4   no-empty-code-lang Language of code can not be empty. 
74:1-74:123 no-long-code       Code Block cannot have too long line. line with 122 characters exceeds code max length 100
docs/practice/agile-development.md
52:27-52:28 space-round-alphabet No space between Chinese and alphabet. '后,Scrum负责人就会
docs/project/basis/settings.md
75:29-75:30 space-round-number   No space between Chinese and number. '的缺陷最多显示10条,可
Lint total 247 files, 0 warnings 782 errors
$ echo $?
1

本地增量检查:

git diff --diff-filter=d --name-only HEAD | grep ".md$" | xargs npx lint-md

持续集成合并请求增量检查:

sh "git diff --diff-filter=d --name-only ${env.MR_TARGET_BRANCH}... | grep '.md\$' | xargs npx lint-md"

fnlint

fnlint 用于检查文件名规范,内置 4 种规范:

  • kebabcase (如 kebab-case.md)
  • camelcase (如 camelCase.js)
  • pascalcase (如 PascalCase.js)
  • snakecase (如 snake_case.rb)

其中「kebabcase」适合用于检查 Markdown 文档的文件名,因为文件名将出现在 URL 中,按照 slug 和域名规范,应使用全小写、连字符,禁止使用大写字母、下划线。

安装:

$ npm install --save-dev fnlint
$ vi .fnlint.json
{
  "basePath": ".",
  "files": "docs/**/*.md",
  "format": "kebabcase",
  "directories": true
}

全量检查:

$ npx fnlint -c .fnlint.json
kebabcase: 9 of 257 file(s) failed linting
/docs/coding.net.md
/docs/best-practices/ci/1minute/#C+makefile.md
/docs/cd/question/FAQ.md
/docs/host/git/git commands.md
/docs/ZZZ/aaa/a.md

增量检查:不支持。

上一篇Git-message 提交规范
最近更新
感谢反馈有用
感谢反馈没用