鸭梨公共文档

主题

3. markdownlint 指南 ​

1. markdownlint 介绍 ​

markdownlint 是一个 MarkDown 格式检查工具，它可以帮助你检查 MarkDown 文件的格式是否符合规范。

有时，你需要临时禁止停用规则，可以使用下面的写法：

markdown
<!-- markdownlint-disable MD001 MD005 -->

这部分内容不会被规则 `MD001` 和 `MD005` 检查。

<!-- markdownlint-enable MD001 MD005 -->

详细的规则和写法参见 markdownlint 配置。

2. ESLint 配置 ​

不推荐此方式来设置，推荐使用特定的插件来支持 MarkDown 文件的格式检查。

如果你在使用前端项目，可以使用这种方法来适配各种项目和编辑器。

bash
pnpm add -D eslint eslint-plugin-markdownlint

配置 .eslintrc.js 文件：

js
module.exports = {
  overrides: [{
    files: ['*.md'],
    parser: 'eslint-plugin-markdownlint/parser',
    rules: {
      // no-multiple-blanks
      'markdownlint/md012': 'warn',
      // line-length
      'markdownlint/md013': 'off',
      // blanks-around-fences
      'markdownlint/md031': ['warn', {
        list_items: false,
      }],
    },
  }],
}

使用 Flat 配置需要安装 eslintrc 支持：

bash
pnpm add -D @eslint/eslintrc

然后配置 eslint.config.js 文件：

js
import { FlatCompat } from '@eslint/eslintrc'

export default [
  ...compat.config({
    overrides: [{
      extends: ['plugin:markdownlint/recommended'],
      files: ['*.md'],
      parser: 'eslint-plugin-markdownlint/parser',
      rules: {
        // no-multiple-blanks
        'markdownlint/md012': 'warn',
        // line-length
        'markdownlint/md013': 'off',
        // blanks-around-fences
        'markdownlint/md031': ['warn', {
          list_items: false,
        }],
      },
    }],
  }),
]

以 VS Code 为例，可配置 settings.json 以便在保存时格式化文档：

json
{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

建议当存在插件 VS Code markdownlint 时，不使用 ESLint 的规则，避免冲突。

如果一定需要使用 ESLint 配置，建议在工作区禁用 VS Code markdownlint 插件，避免和 ESLint 的规则冲突，禁用方法是在此插件一项中右键选择 禁用(工作区)，然后重新打开即可。

3. VS Code 配置 ​

VS Code 安装 markdownlint 插件：

bash
code --install-extension DavidAnson.vscode-markdownlint

下面通过创建 .markdownlint.yaml 来描述 markdownlint 的规则，例如：

yaml
default: true

# line-length (default: 80)
MD013: false

# blanks-around-fences (allow only code in list)
MD031:
  list_items: false

4. 命令行工具 ​

markdownlint 可以作为命令安装到全局：

bash
pnpm install -g markdownlint-cli