1. 授权认证
  2. 获取用户个人信息
  3. 项目协同
  4. 代码托管
  5. 持续集成
  6. 制品仓库
  7. 测试管理
  8. 文档管理
  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 中文书写规范,内置「阮一峰中文技术文档规范」,常见规则如下:

  • 中文与英文之间需要空格
  • 中文与数字之间需要空格
  • 代码块需声明编程语言(参考: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 commit message 规范
最近更新
感谢反馈有用
感谢反馈没用