markdownlint-configuration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdownlint Configuration

Markdownlint 配置

Master markdownlint configuration including rule management, configuration files, inline comment directives, style inheritance, and schema validation for consistent Markdown linting.

精通markdownlint配置，包括规则管理、配置文件、内联注释指令、样式继承以及模式验证，以实现一致的Markdown代码检查。

Overview

概述

Markdownlint is a Node.js style checker and linter for Markdown/CommonMark files. It helps enforce consistent formatting and style across Markdown documentation by providing a comprehensive set of rules that can be customized through configuration files or inline comments.

Markdownlint 是一款基于Node.js的Markdown/CommonMark文件样式检查器与代码检查工具。它通过提供一套可通过配置文件或内联注释自定义的全面规则，帮助在Markdown文档中强制执行一致的格式与样式。

Installation and Setup

安装与设置

Basic Installation

基础安装

Install markdownlint in your project:

bash

npm install --save-dev markdownlint markdownlint-cli

在你的项目中安装markdownlint：

bash

npm install --save-dev markdownlint markdownlint-cli

or

pnpm add -D markdownlint markdownlint-cli

or

yarn add -D markdownlint markdownlint-cli

undefined

yarn add -D markdownlint markdownlint-cli

undefined

Verify Installation

验证安装

bash

npx markdownlint --version

bash

npx markdownlint --version

Configuration File Structure

配置文件结构

Basic .markdownlint.json

基础 .markdownlint.json

Create a

.markdownlint.json

file in your project root:

json

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

This configuration:

Enables all default rules via
```
"default": true
```
Configures MD003 (heading style) to use ATX closed format
Sets MD007 (unordered list indentation) to 4 spaces
Disables the no-hard-tabs rule
Disables all whitespace rules

在项目根目录创建

.markdownlint.json

文件：

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规则
禁用所有空白相关规则

Rule Naming Conventions

规则命名约定

Rules can be referenced by their ID (MD###) or friendly name:

json

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

Both ID and friendly name work identically.

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

json

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

ID和友好名称的作用完全相同。

Configuration Options

配置选项

Enable/Disable All Rules

启用/禁用所有规则

json

{
  "default": true
}

When

"default": false

, only explicitly enabled rules are active:

json

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

json

{
  "default": true
}

当

"default": false

时，仅显式启用的规则生效：

json

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

Rule-Specific Parameters

规则特定参数

Heading Style (MD003)

标题样式（MD003）

json

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

Options:

"atx"

"atx_closed"

"setext"

"setext_with_atx"

"setext_with_atx_closed"

json

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

选项：

"atx"

"atx_closed"

"setext"

"setext_with_atx"

"setext_with_atx_closed"

Unordered List Style (MD004)

无序列表样式（MD004）

json

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

Options:

"asterisk"

"dash"

"plus"

"consistent"

"sublist"

json

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

选项：

"asterisk"

"dash"

"plus"

"consistent"

"sublist"

List Indentation (MD007)

列表缩进（MD007）

json

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

json

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

Line Length (MD013)

行长度（MD013）

json

{
  "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
  }
}

json

{
  "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
  }
}

No Trailing Spaces (MD009)

无尾随空格（MD009）

json

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

json

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

No Inline HTML (MD033)

禁止内联HTML（MD033）

json

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

json

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

Horizontal Rule Style (MD035)

水平分隔线样式（MD035）

json

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

Options:

"---"

"***"

"___"

, or custom like

"- - -"

json

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

选项：

"---"

"***"

"___"

，或自定义格式如

"- - -"

First Line Heading (MD041)

首行标题（MD041）

json

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

json

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

Required Headings

必填标题

json

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

json

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

Proper Names (MD044)

专有名词（MD044）

json

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

json

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

Inline Configuration Comments

内联配置注释

Disable Rules for Entire File

禁用整个文件的规则

markdown

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

markdown

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

This file has no linting applied

此文件不应用任何代码检查

Any markdown content here will not be checked.

undefined

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

undefined

Disable Specific Rules for File

禁用文件的特定规则

markdown

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

markdown

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

Long lines and HTML are allowed in this file

此文件允许长行与HTML内容

This line can be as long as you want without triggering MD013.

<div>Inline HTML is also allowed</div> ```

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

<div>内联HTML也是允许的</div> ```

Disable Rules Temporarily

临时禁用规则

markdown

<!-- markdownlint-disable MD033 -->

<div class="custom-block">
  HTML content here
</div>

<!-- markdownlint-enable MD033 -->

Regular markdown content with rules enforced.

markdown

<!-- markdownlint-disable MD033 -->

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

<!-- markdownlint-enable MD033 -->

恢复规则强制执行的常规Markdown内容。

Disable for Single Line

禁用单行规则

markdown

This line follows all rules.

Long line that exceeds limit <!-- markdownlint-disable-line MD013 -->

This line follows all rules again.

markdown

此行遵循所有规则。

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

此行再次遵循所有规则。

Disable for Next Line

禁用下一行规则

markdown

<!-- markdownlint-disable-next-line MD013 -->
This is a very long line that would normally trigger the line-length rule but won't because of the comment above.

This line follows normal rules.

markdown

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

此行遵循常规规则。

Capture and Restore Configuration

捕获与恢复配置

markdown

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

Any violations allowed here.

<!-- markdownlint-restore -->

Back to original configuration.

markdown

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

此区域允许任何违规内容。

<!-- markdownlint-restore -->

恢复为原始配置。

Configure Rules Inline

内联配置规则

markdown

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

markdown

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

Document Title

文档标题

Rest of document follows inline configuration.

undefined

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

undefined

Configuration File Formats

配置文件格式

JSON Configuration

JSON配置

.markdownlint.json

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"]
  }
}

.markdownlint.json

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 Configuration

YAML配置

.markdownlint.yaml

yaml

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

.markdownlint.yaml

yaml

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

JavaScript Configuration

JavaScript配置

.markdownlint.js

javascript

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

.markdownlint.js

javascript

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

Configuration Inheritance

配置继承

Extending Base Configurations

扩展基础配置

Create a base configuration:

base.json

json

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

Extend it in your project:

custom.json

json

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

创建基础配置：

base.json

json

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

在项目中扩展它：

custom.json

json

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

Using Predefined Styles

使用预定义样式

Markdownlint includes predefined style configurations:

json

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

Available styles:

```
markdownlint/style/relaxed
```
- Less strict rules
```
markdownlint/style/prettier
```
- Compatible with Prettier

Markdownlint包含预定义样式配置：

json

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

可用样式：

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

Schema Validation

模式验证

Enable IDE Support

启用IDE支持

Include the

$schema

property for autocomplete and validation:

json

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

This enables:

Autocomplete for rule names
Validation of configuration values
Inline documentation in supported editors

包含

$schema

属性以获得自动补全与验证：

json

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

这将启用：

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

Project-Specific Configurations

项目特定配置

Per-Directory Configuration

按目录配置

Place

.markdownlint.json

in specific directories:

project/
├── .markdownlint.json          # Root config
├── docs/
│   ├── .markdownlint.json      # Docs-specific config
│   └── guides/
│       └── .markdownlint.json  # Guides-specific config

在特定目录中放置

.markdownlint.json

：

project/
├── .markdownlint.json          # 根配置
├── docs/
│   ├── .markdownlint.json      # 文档专属配置
│   └── guides/
│       └── .markdownlint.json  # 指南专属配置

Monorepo Configuration

单体仓库配置

Root

.markdownlint.json

json

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

Package-specific

packages/api/docs/.markdownlint.json

json

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

根目录

.markdownlint.json

json

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

包专属配置

packages/api/docs/.markdownlint.json

json

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

Common Configuration Patterns

常见配置模式

Strict Documentation Standards

严格文档标准

json

{
  "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"
    ]
  }
}

json

{
  "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"
    ]
  }
}

Relaxed Blog/Article Style

宽松博客/文章样式

json

{
  "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
}

json

{
  "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
}

Technical Documentation

技术文档

json

{
  "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"
  }
}

json

{
  "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 Template

README模板

json

{
  "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
  }
}

json

{
  "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
  }
}

When to Use This Skill

何时使用此技能

Setting up markdownlint in new projects
Configuring linting rules for documentation
Creating custom rule configurations for teams
Troubleshooting configuration issues
Establishing Markdown style guides
Migrating from other Markdown linters
Enforcing consistent documentation standards
Configuring monorepo Markdown linting

在新项目中设置markdownlint
为文档配置代码检查规则
为团队创建自定义规则配置
排查配置问题
建立Markdown样式指南
从其他Markdown检查工具迁移
强制执行一致的文档标准
配置单体仓库的Markdown代码检查

Best Practices

最佳实践

Use Schema Validation - Always include
```
$schema
```
for IDE support
Start with Defaults - Begin with
```
"default": true
```
and disable selectively
Document Exceptions - Comment why specific rules are disabled
Consistent Naming - Use either rule IDs or friendly names, not both
Version Control Config - Commit
```
.markdownlint.json
```
to repository
Team Agreement - Discuss rule changes with team before applying
Progressive Adoption - Gradually enable stricter rules over time
Test Changes - Run linter after configuration changes
Use Inheritance - Leverage extends for shared configurations
Inline Sparingly - Prefer file-level config over inline comments
Monitor Rule Updates - Review new rules in markdownlint updates
Environment-Specific - Use different configs for different doc types
Automation Integration - Include linting in pre-commit hooks
Regular Review - Periodically review and update configurations
Clear Comments - Add comments explaining complex configurations

使用模式验证 - 始终包含
```
$schema
```
以获得IDE支持
从默认规则开始 - 以
```
"default": true
```
为起点，选择性禁用规则
记录例外情况 - 注释说明禁用特定规则的原因
命名一致 - 统一使用规则ID或友好名称，不要混用
版本控制配置 - 将
```
.markdownlint.json
```
提交到代码仓库
团队共识 - 应用规则变更前与团队讨论
渐进式采用 - 随时间逐步启用更严格的规则
测试变更 - 配置变更后运行代码检查工具
使用继承 - 利用extends实现共享配置
谨慎使用内联注释 - 优先使用文件级配置而非内联注释
关注规则更新 - 查看markdownlint更新中的新规则
区分环境配置 - 为不同类型的文档使用不同配置
集成自动化 - 将代码检查纳入提交前钩子
定期回顾 - 定期回顾并更新配置
清晰注释 - 为复杂配置添加说明注释

Common Pitfalls

常见陷阱

Conflicting Rules - Enabling contradictory rules (e.g., different heading styles)
Over-Configuration - Specifying too many inline disable comments
Missing Schema - Not including
```
$schema
```
for validation
Incorrect Paths - Using wrong paths in extends property
Rule Name Typos - Misspelling rule names (fails silently)
JSON Syntax Errors - Invalid JSON breaks configuration parsing
Overly Strict - Enabling strict rules without team buy-in
Ignoring Warnings - Dismissing legitimate style issues
No Base Config - Not establishing project-wide defaults
Hardcoded Values - Not using variables for repeated values
Stale Configurations - Not updating after markdownlint upgrades
Missing Allowed Elements - Blocking necessary HTML elements
Inconsistent Inheritance - Different base configs across projects
No Testing - Not testing configuration before committing
Unclear Disable Reasons - Using disable without explanation

规则冲突 - 启用矛盾的规则（如不同的标题样式）
过度配置 - 添加过多内联禁用注释
缺少模式 - 未包含
```
$schema
```
进行验证
路径错误 - 在extends属性中使用错误路径
规则名称拼写错误 - 规则名称拼写错误（会静默失败）
JSON语法错误 - 无效JSON会导致配置解析失败
过于严格 - 在未获得团队认可的情况下启用严格规则
忽略警告 - 忽略合理的样式问题
缺少基础配置 - 未建立项目级默认配置
硬编码值 - 未对重复值使用变量
配置过时 - markdownlint升级后未更新配置
缺少允许元素 - 阻止了必要的HTML元素
继承不一致 - 跨项目使用不同的基础配置
未测试 - 提交前未测试配置
禁用原因不明确 - 使用禁用注释但未说明原因