名称: markdownlint-配置用户可调用: false 描述: 配置 markdownlint 规则和选项，包括规则管理、配置文件、内联注释和样式继承。允许工具: [Bash, Read]

Markdownlint 配置

掌握 markdownlint 配置，包括规则管理、配置文件、内联注释指令、样式继承和模式验证，以确保 Markdown 格式化的一致性。

概述

Markdownlint 是一个 Node.js 样式检查器和 Markdown/CommonMark 文件的 linter。它通过提供一套可自定义的规则，帮助强制执行 Markdown 文档的一致格式和样式，这些规则可以通过配置文件或内联注释进行配置。

安装和设置

基本安装

在项目中安装 markdownlint：

npm install --save-dev markdownlint markdownlint-cli
# 或
pnpm add -D markdownlint markdownlint-cli
# 或
yarn add -D markdownlint markdownlint-cli

验证安装

npx markdownlint --version

配置文件结构

基本的 .markdownlint.json

在项目根目录中创建 .markdownlint.json 文件：

{
  "default": true,
  "MD003": { "style": "atx_closed" },
  "MD007": { "indent": 4 },
  "no-hard-tabs": false,
  "whitespace": false
}

此配置：

通过 "default": true 启用所有默认规则
配置 MD003（标题样式）使用 ATX 封闭格式
设置 MD007（无序列表缩进）为 4 个空格
禁用 no-hard-tabs 规则
禁用所有空白规则

规则命名约定

规则可以通过其 ID（MD###）或友好名称引用：

{
  "MD001": false,
  "heading-increment": false,
  "MD003": { "style": "atx" },
  "heading-style": { "style": "atx" },
  "no-inline-html": {
    "allowed_elements": ["strong", "em", "br"]
  }
}

ID 和友好名称功能相同。

配置选项

启用/禁用所有规则

{
  "default": true
}

当 "default": false 时，只有明确启用的规则生效：

{
  "default": false,
  "MD001": true,
  "MD003": { "style": "atx" },
  "line-length": true
}

规则特定参数

标题样式 (MD003)

{
  "heading-style": {
    "style": "atx"
  }
}

选项："atx", "atx_closed", "setext", "setext_with_atx", "setext_with_atx_closed"

无序列表样式 (MD004)

{
  "ul-style": {
    "style": "asterisk"
  }
}

选项："asterisk", "dash", "plus", "consistent", "sublist"

列表缩进 (MD007)

{
  "ul-indent": {
    "indent": 4,
    "start_indented": true
  }
}

行长度 (MD013)

{
  "line-length": {
    "line_length": 100,
    "heading_line_length": 120,
    "code_block_line_length": 120,
    "code_blocks": true,
    "tables": false,
    "headings": true,
    "strict": false,
    "stern": false
  }
}

无尾随空格 (MD009)

{
  "no-trailing-spaces": {
    "br_spaces": 2,
    "list_item_empty_lines": false,
    "strict": false
  }
}

无内联 HTML (MD033)

{
  "no-inline-html": {
    "allowed_elements": [
      "strong",
      "em",
      "br",
      "sub",
      "sup",
      "kbd",
      "details",
      "summary"
    ]
  }
}

水平线样式 (MD035)

{
  "hr-style": {
    "style": "---"
  }
}

选项："---", "***", "___", 或自定义如 "- - -"

首行标题 (MD041)

{
  "first-line-heading": {
    "level": 1,
    "front_matter_title": ""
  }
}

必需标题

{
  "required-headings": {
    "headings": [
      "# Title",
      "## Description",
      "## Examples",
      "## Resources"
    ]
  }
}

专有名词 (MD044)

{
  "proper-names": {
    "names": [
      "JavaScript",
      "TypeScript",
      "GitHub",
      "markdownlint",
      "npm"
    ],
    "code_blocks": false
  }
}

内联配置注释

禁用整个文件的规则

<!-- markdownlint-disable-file -->

# 此文件无格式化检查

此处的任何 Markdown 内容都不会被检查。

禁用文件中特定规则

<!-- markdownlint-disable-file MD013 MD033 -->

# 此文件允许长行和 HTML

此行可以任意长，不会触发 MD013。

<div>也允许内联 HTML</div>

临时禁用规则

<!-- markdownlint-disable MD033 -->

<div class="custom-block">
  HTML 内容在此
</div>

<!-- markdownlint-enable MD033 -->

规则生效的常规 Markdown 内容。

禁用单行

此行遵循所有规则。

超过限制的长行 <!-- markdownlint-disable-line MD013 -->

此行再次遵循所有规则。

禁用下一行

<!-- markdownlint-disable-next-line MD013 -->
这是一个非常长的行，通常会触发行长度规则，但由于上面的注释不会触发。

此行遵循正常规则。

捕获和恢复配置

<!-- markdownlint-capture -->
<!-- markdownlint-disable -->

此处允许任何违规。

<!-- markdownlint-restore -->

回到原始配置。

内联配置规则

<!-- markdownlint-configure-file {
  "line-length": {
    "line_length": 120
  },
  "no-inline-html": {
    "allowed_elements": ["strong", "em"]
  }
} -->

# 文档标题

文档其余部分遵循内联配置。

配置文件格式

JSON 配置

.markdownlint.json：

{
  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",
  "default": true,
  "MD003": { "style": "atx" },
  "MD007": { "indent": 2 },
  "MD013": {
    "line_length": 100,
    "code_blocks": false
  },
  "MD033": {
    "allowed_elements": ["br", "strong", "em"]
  }
}

YAML 配置

.markdownlint.yaml：

default: true
MD003:
  style: atx
MD007:
  indent: 2
MD013:
  line_length: 100
  code_blocks: false
MD033:
  allowed_elements:
    - br
    - strong
    - em

JavaScript 配置

.markdownlint.js：

module.exports = {
  default: true,
  MD003: { style: "atx" },
  MD007: { indent: 2 },
  MD013: {
    line_length: 100,
    code_blocks: false
  },
  MD033: {
    allowed_elements: ["br", "strong", "em"]
  }
};

配置继承

扩展基础配置

创建基础配置：

base.json：

{
  "default": true,
  "line-length": {
    "line_length": 100
  }
}

在项目中扩展它：

custom.json：

{
  "extends": "base.json",
  "no-inline-html": false,
  "line-length": {
    "line_length": 120
  }
}

使用预定义样式

Markdownlint 包括预定义的样式配置：

{
  "extends": "markdownlint/style/relaxed"
}

可用样式：

markdownlint/style/relaxed - 较宽松的规则
markdownlint/style/prettier - 与 Prettier 兼容

模式验证

启用 IDE 支持

包含 $schema 属性以启用自动完成和验证：

{
  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",
  "default": true
}

这启用：

规则名称的自动完成
配置值的验证
支持编辑器中的内联文档

项目特定配置

每目录配置

将 .markdownlint.json 放置在特定目录中：

项目/
├── .markdownlint.json          # 根配置
├── 文档/
│   ├── .markdownlint.json      # 文档特定配置
│   └── 指南/
│       └── .markdownlint.json  # 指南特定配置

Monorepo 配置

根 .markdownlint.json：

{
  "default": true,
  "line-length": {
    "line_length": 100
  }
}

包特定 packages/api/docs/.markdownlint.json：

{
  "extends": "../../../.markdownlint.json",
  "no-inline-html": {
    "allowed_elements": ["code", "pre", "div"]
  }
}

常见配置模式

严格文档标准

{
  "default": true,
  "heading-style": { "style": "atx" },
  "ul-style": { "style": "dash" },
  "ol-prefix": { "style": "ordered" },
  "line-length": {
    "line_length": 80,
    "strict": true
  },
  "no-trailing-spaces": {
    "strict": true
  },
  "no-inline-html": false,
  "first-line-heading": {
    "level": 1
  },
  "required-headings": {
    "headings": [
      "# Title",
      "## Description",
      "## Usage",
      "## API"
    ]
  }
}

宽松博客/文章样式

{
  "default": true,
  "line-length": false,
  "no-inline-html": {
    "allowed_elements": [
      "img",
      "a",
      "strong",
      "em",
      "br",
      "div",
      "span"
    ]
  },
  "no-duplicate-heading": {
    "siblings_only": true
  },
  "first-line-heading": false,
  "single-title": false
}

技术文档

{
  "default": true,
  "line-length": {
    "line_length": 120,
    "code_blocks": false,
    "tables": false
  },
  "no-inline-html": {
    "allowed_elements": [
      "details",
      "summary",
      "kbd",
      "sub",
      "sup",
      "br"
    ]
  },
  "code-block-style": {
    "style": "fenced"
  },
  "code-fence-style": {
    "style": "backtick"
  },
  "emphasis-style": {
    "style": "asterisk"
  },
  "strong-style": {
    "style": "asterisk"
  }
}

README 模板

{
  "default": true,
  "line-length": {
    "line_length": 100,
    "tables": false,
    "code_blocks": false
  },
  "no-inline-html": {
    "allowed_elements": [
      "img",
      "br",
      "details",
      "summary",
      "sup"
    ]
  },
  "required-headings": {
    "headings": [
      "# *",
      "## Installation",
      "## Usage",
      "## License"
    ]
  },
  "first-line-heading": {
    "level": 1
  }
}

何时使用此技能

在新项目中设置 markdownlint
为文档配置格式化规则
为团队创建自定义规则配置
解决配置问题
建立 Markdown 样式指南
从其他 Markdown linter 迁移
强制执行一致文档标准
配置 monorepo 的 Markdown 格式化

最佳实践

使用模式验证 - 始终包含 $schema 以获取 IDE 支持
从默认开始 - 以 "default": true 开始，然后选择性地禁用
记录例外 - 注释为什么禁用特定规则
一致命名 - 使用规则 ID 或友好名称，不要混用
版本控制配置 - 提交 .markdownlint.json 到仓库
团队协议 - 应用规则变更前与团队讨论
渐进式采用 - 逐步启用更严格的规则
测试变更 - 配置更改后运行 linter
使用继承 - 利用扩展共享配置
内联谨慎使用 - 优先文件级配置而非内联注释
监控规则更新 - 查看 markdownlint 更新中的新规则
环境特定 - 为不同文档类型使用不同配置
自动化集成 - 在预提交钩子中包含格式化
定期审查 - 定期审查并更新配置
清晰注释 - 添加注释解释复杂配置

常见陷阱

冲突规则 - 启用矛盾规则（例如，不同标题样式）
过度配置 - 指定太多内联禁用注释
缺少模式 - 不包含 $schema 进行验证
错误路径 - 在 extends 属性中使用错误路径
规则名称拼写错误 - 错误拼写规则名称（静默失败）
JSON 语法错误 - 无效 JSON 破坏配置解析
过于严格 - 在团队同意前启用严格规则
忽略警告 - 忽略合法样式问题
无基础配置 - 不建立项目范围的默认值
硬编码值 - 不为重复值使用变量
过时配置 - 升级 markdownlint 后不更新配置
缺少允许元素 - 阻止必要的 HTML 元素
不一致继承 - 项目间不同基础配置
无测试 - 提交前不测试配置
不清禁用原因 - 使用禁用但无解释

名称: markdownlint-配置 用户可调用: false 描述: 配置 markdownlint 规则和选项，包括规则管理、配置文件、内联注释和样式继承。 允许工具: [Bash, Read]