Back to Details

lint-markdown

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Markdown Linting with 
markdownlint-cli2

使用
markdownlint-cli2
进行Markdown检查

Workflow

工作流程

1. Run auto-fix first

1. 先运行自动修复

bash
markdownlint-cli2 --fix "<filepath>"
This resolves ~30 fixable rules automatically (white space, list style, blank lines, emphasis style, etc.).
bash
markdownlint-cli2 --fix "<filepath>"
这会自动解决约30项可修复规则（空格、列表样式、空行、强调样式等）。

2. Re-lint to find remaining issues

2. 重新检查以发现剩余问题

bash
markdownlint-cli2 "<filepath>" 2>&1
  • Exit code 
    0
    = clean. Stop here.
  • Exit code 
    1
    = errors remain. Continue to step 3.
Parse each error line: 
<file>:<line>[:<col>] <MDXXX>/<alias> <description>
bash
markdownlint-cli2 "<filepath>" 2>&1
  • 退出码
    0
    = 无问题。到此结束。
  • 退出码
    1
    = 仍有错误。继续执行步骤3。
解析每条错误行：
<file>:<line>[:<col>] <MDXXX>/<alias> <description>

3. Manually fix remaining errors

3. 手动修复剩余错误

Read the file, then apply fixes with the Edit tool. For rule-specific fix strategies, consult references/rules.md.
Common non-fixable issues and quick fixes:
  • MD040 (fenced-code-language): Add a language identifier after opening 
    ```
    (e.g., 
    ```bash
    , 
    ```json
    ). Use 
    text
    if no language applies.
  • MD033 (no-inline-html): Replace HTML tags with Markdown equivalents. Remove tags with no Markdown equivalent if they are non-essential.
  • MD001 (heading-increment): Ensure headings increase by one level only (
    #
    then 
    ##
    , never 
    #
    then 
    ###
    ).
  • MD045 (no-alt-text): Add descriptive alt text to images: 
    ![description](url)
    .
打开文件，使用编辑工具进行修复。如需特定规则的修复策略，请参考references/rules.md。
常见的不可自动修复问题及快速修复方案：
  • MD040 (fenced-code-language)：在开头的
    ```
    后添加语言标识符（例如
    ```bash
    , 
    ```json
    ）。如果没有适用语言，使用
    text
    。
  • MD033 (no-inline-html)：用Markdown等效语法替换HTML标签。如果是不必要的标签且无Markdown等效语法，则直接移除。
  • MD001 (heading-increment)：确保标题级别仅递增一级（
    #
    之后是
    ##
    ，不能直接从
    #
    跳到
    ###
    ）。
  • MD045 (no-alt-text)：为图片添加描述性替代文本：
    ![描述](url)
    。

4. Verify clean

4. 验证无问题

bash
markdownlint-cli2 "<filepath>" 2>&1
Repeat steps 3-4 until exit code is 
0
.
bash
markdownlint-cli2 "<filepath>" 2>&1
重复步骤3-4直到退出码为
0
。

Notes

注意事项

  • Always quote file paths in commands to handle spaces.
  • If a 
    .markdownlint-cli2.jsonc
    , 
    .markdownlint.yaml
    , or similar config exists in the project, respect its rule overrides.
  • When linting multiple files, use globs: 
    markdownlint-cli2 --fix "**/*.md"
    .
  • The 
    --fix
    flag modifies files in place. It is safe to run repeatedly.
  • 命令中的文件路径始终要加引号，以处理含空格的路径。
  • 如果项目中存在
    .markdownlint-cli2.jsonc
    , 
    .markdownlint.yaml
    或类似配置文件，请遵循其规则覆盖设置。
  • 检查多个文件时，使用通配符：
    markdownlint-cli2 --fix "**/*.md"
    。
  • --fix
    参数会直接修改文件。可安全重复运行。