markdownlint-configuration

Markdownlint Configuration 介绍如何配置 markdownlint，以实现一致、可维护的 Markdown 样式检查。

【用途】 Markdownlint 是 Node.js 的 Markdown/CommonMark 样式检查器与 Linter，用于在 Markdown 文档中强制统一的格式与风格。本技能覆盖规则管理、配置文件、内联注释指令、样式继承与 schema 校验。

【安装与验证】使用 npm、pnpm 或 yarn 安装：

npm install --save-dev markdownlint markdownlint-cli

或

pnpm add -D markdownlint markdownlint-cli

或

yarn add -D markdownlint markdownlint-cli

安装后可通过 npx markdownlint --version 验证。

【配置文件】在项目根目录创建 .markdownlint.json，例如：

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

其中 "default": true 启用全部默认规则；MD003 设置标题使用 ATX closed 格式；MD007 将无序列表缩进设为 4 空格；并禁用了 no-hard-tabs 与所有 whitespace 规则。

规则可用 ID（MD###）或友好名称引用，两者等价：

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

当 "default": false 时，只有显式启用的规则生效。

【常见规则参数】

标题样式（MD003）：可选 "atx"、"atx_closed"、"setext"、"setext_with_atx"、"setext_with_atx_closed"。
无序列表样式（MD004）：可选 "asterisk"、"dash"、"plus"、"consistent"、"sublist"。
列表缩进（MD007）：可设置 indent 与 start_indented。
行长度（MD013）：可设置 line_length、heading_line_length、code_block_line_length、code_blocks、tables、headings、strict、stern。
行尾空格（MD009）：可设置 br_spaces、list_item_empty_lines、strict。
内联 HTML（MD033）：通过 allowed_elements 允许特定元素，如 strong、em、br、sub、sup、kbd、details、summary。
水平线样式（MD035）：可设置 "---"、"***"、"___" 或自定义形式。
首行标题（MD041）：可设置 level、front_matter_title。
必需标题：通过 required-headings 列出必须出现的标题，如 "# Title"、"## Description"、"## Examples"、"## Resources"。
专有名称（MD044）：通过 names 列表指定正确写法，如 JavaScript、TypeScript、GitHub、markdownlint、npm，并可设置 code_blocks。

【内联配置注释】

对整个文件禁用：
对文件禁用特定规则：
临时禁用与恢复： ...
单行禁用：
下一行禁用：
捕获与恢复配置： /
内联配置规则（markdownlint-configure-file）：可传入 JSON，覆盖 line-length、no-inline-html 等设置。

【配置格式】支持 JSON（.markdownlint.json）、YAML（.markdownlint.yaml）与 JavaScript（.markdownlint.js）。JSON 示例中可加入 $schema 以启用编辑器支持： "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json"

【配置继承与预设样式】可通过 "extends": "base.json" 继承基础配置并覆盖部分规则。也可继承官方预设：

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

【Schema 校验】加入 $schema 可在支持的编辑器中获得规则名自动补全、配置值校验与内联文档。

【项目级与 monorepo 配置】可在不同目录放置 .markdownlint.json 实现按目录配置。Monorepo 中，包级配置可通过 "extends": "../../../.markdownlint.json" 继承根配置，再按需覆盖。

【常见配置模式】资料给出严格文档标准、宽松博客/文章风格、技术文档、README 模板等示例，分别组合了标题样式、列表样式、行长度、内联 HTML 允许元素、必需标题等规则。具体参数可参考上述规则说明。

【适用场景】

在新项目中设置 markdownlint
为文档配置 Lint 规则
为团队创建自定义规则配置
排查配置问题
建立 Markdown 风格指南
从其他 Markdown Linter 迁移
强制执行一致的文档标准
配置 monorepo 的 Markdown Lint

【最佳实践】使用 schema 校验、从默认规则开始再选择性禁用、注释说明禁用原因、统一使用规则 ID 或友好名称、将配置提交版本控制、与团队协商规则变更、渐进式采用更严格规则、修改后运行 Linter 测试、利用 extends 共享配置、谨慎使用内联注释并优先文件级配置、关注规则更新、按文档类型区分配置、集成到 pre-commit 钩子、定期审查配置、为复杂配置添加注释。

【常见陷阱】规则冲突、过度配置、缺少 schema、extends 路径错误、规则名拼写错误（会静默失败）、JSON 语法错误、规则过严、忽略警告、缺少基础配置、硬编码值、配置过时、allowed_elements 遗漏、继承不一致、未测试即提交、禁用原因不明确。

【资源】 markdownlint GitHub 仓库、markdownlint 规则文档、配置 Schema、markdownlint-cli 文档、自定义规则指南。

技能介绍

或

或