Back to Details

markdown-linter-fixer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Markdown Linter Fixer

Markdown代码检查修复工具

Overview

概述

Systematically fix linting issues in 
*.md
files using markdownlint-cli2 through a structured workflow that diagnoses, fixes automatically where possible, and guides manual fixes when needed.
通过结构化工作流，使用markdownlint-cli2系统性修复
*.md
文件中的代码检查问题，该工作流会诊断问题、尽可能自动修复，并在需要时指导手动修复。

When to Use This Skill

何时使用此技能

Use this skill when:
  • Fixing markdown linting errors in projects
  • Standardizing markdown formatting across multiple files
  • Addressing ordered list numbering issues (MD029)
  • Preparing markdown documentation for quality standards
  • Setting up markdown linting for the first time in a project
在以下场景使用此技能：
  • 修复项目中的Markdown代码检查错误
  • 统一多个文件的Markdown格式
  • 解决有序列表编号问题（MD029）
  • 为符合质量标准准备Markdown文档
  • 首次在项目中设置Markdown代码检查

Workflow Process

工作流流程

Phase 1: Environment Setup & Prerequisites

第一阶段：环境配置与前置条件

Verify markdownlint-cli2 Installation

验证markdownlint-cli2是否安装

Check if markdownlint-cli2 is installed:
bash
markdownlint-cli2 --version
If missing, install it globally via npm:
bash
npm install -g markdownlint-cli2
Handle any permission or installation errors by suggesting:
  • Local installation: 
    npm install --save-dev markdownlint-cli2
  • Using npx: 
    npx markdownlint-cli2
  • User-specific npm directory configuration
检查是否已安装markdownlint-cli2：
bash
markdownlint-cli2 --version
如果未安装，通过npm全局安装：
bash
npm install -g markdownlint-cli2
针对权限或安装错误，建议以下解决方案：
  • 本地安装：
    npm install --save-dev markdownlint-cli2
  • 使用npx：
    npx markdownlint-cli2
  • 配置用户专属npm目录

Configuration File Check

配置文件检查

Look for existing markdown configuration files in the project root:
  • .markdownlint-cli2.jsonc
  • .markdownlint.json
  • .markdownlint.yaml
  • .markdownlint.yml
  • .markdownlintrc
If none exist, create 
.markdownlint-cli2.jsonc
with:
json
{
  "config": {
    "MD013": false
  },
  "ignores": []
}
This disables max line length warnings while keeping other rules active. The 
ignores
array can be used to exclude specific files from linting (e.g., example files with intentional errors).
IMPORTANT - Configuration Policy:
  • Do not ignore/hide linting errors by modifying 
    .markdownlint-cli2.jsonc
  • Only modify the 
    ignores
    array     based on:
    • Explicit user input or approval
    • Content from 
      .gitignore
      file (files already ignored by git)
  • Always ask the user before adding files to the ignore list
  • Never suppress errors without user consent - fix them instead
在项目根目录查找现有Markdown配置文件：
  • .markdownlint-cli2.jsonc
  • .markdownlint.json
  • .markdownlint.yaml
  • .markdownlint.yml
  • .markdownlintrc
如果不存在，创建
.markdownlint-cli2.jsonc
文件，内容如下：
json
{
  "config": {
    "MD013": false
  },
  "ignores": []
}
此配置会禁用最大行长度警告，同时保留其他规则。
ignores
数组可用于排除特定文件（例如包含故意错误的示例文件）。
重要 - 配置规则：
  • 不要通过修改
    .markdownlint-cli2.jsonc
    来忽略/隐藏代码检查错误
  • 仅可基于以下情况修改
    ignores
    数组    ：
    • 用户明确输入或批准
    • .gitignore
      文件中的内容（已被Git忽略的文件）
  • 添加文件到忽略列表前务必询问用户
  • 未经用户同意绝不要抑制错误 - 应修复错误

Phase 2: Diagnostic Assessment

第二阶段：诊断评估

Initial Root-Level Scan

初始根目录扫描

Run linter on root-level markdown files:
bash
markdownlint-cli2 "*.md"
Document all issues found, including:
  • Error codes (e.g., MD029, MD001, MD032)
  • File names and line numbers
  • Brief description of each issue
对根目录下的Markdown文件运行代码检查：
bash
markdownlint-cli2 "*.md"
记录所有发现的问题，包括：
  • 错误代码（如MD029、MD001、MD032）
  • 文件名和行号
  • 每个问题的简要描述

Comprehensive Recursive Scan

全面递归扫描

Scan all markdown files including subdirectories:
bash
markdownlint-cli2 "**/*.md"
This includes files in directories like:
  • docs/
  • guides/
  • Any other subdirectories containing markdown
Create a complete inventory of all issues across the project.
扫描所有Markdown文件，包括子目录：
bash
markdownlint-cli2 "**/*.md"
这包括以下目录中的文件：
  • docs/
  • guides/
  • 其他包含Markdown文件的子目录
创建项目中所有问题的完整清单。

Phase 3: Issue Analysis

第三阶段：问题分析

Categorize Errors by Type

按错误类型分类

Group all identified linting errors by error code:
  • Track frequency of each error type
  • Identify which errors are auto-fixable
  • Flag special attention areas (especially MD029, which often requires understanding indentation issues)
Common error types:
  • MD001: Heading levels should increment by one level at a time
  • MD009: Trailing spaces
  • MD010: Hard tabs
  • MD012: Multiple consecutive blank lines
  • MD029: Ordered list item prefix (requires special attention - often caused by improper indentation)
  • MD032: Lists should be surrounded by blank lines
  • MD047: Files should end with a single newline character
Document patterns such as:
  • "Found 15 MD029 errors across 5 files"
  • "MD032 appears in all documentation files"
  • "MD029 errors primarily in files with code blocks within lists"
按错误代码对所有识别出的代码检查错误进行分组：
  • 跟踪每种错误类型的出现频率
  • 识别可自动修复的错误
  • 标记需要特别关注的领域（尤其是MD029，通常需要理解缩进问题）
常见错误类型：
  • MD001：标题级别应每次递增一级
  • MD009：尾随空格
  • MD010：硬制表符
  • MD012：多个连续空行
  • MD029：有序列表项前缀（需要特别关注 - 通常由缩进不当引起）
  • MD032：列表前后应添加空行
  • MD047：文件应以单个换行符结尾
记录模式，例如：
  • "在5个文件中发现15个MD029错误"
  • "所有文档文件中均出现MD032错误"
  • "MD029错误主要出现在列表中包含代码块的文件"

Phase 4: Automatic Fixes

第四阶段：自动修复

Execute Auto-Fix

执行自动修复

Run the auto-fix command to correct all auto-fixable issues:
bash
markdownlint-cli2 "**/*.md" --fix
This command will:
  • Automatically fix formatting issues where possible
  • Preserve original content intent
  • Modify files in place
运行自动修复命令，纠正所有可自动修复的问题：
bash
markdownlint-cli2 "**/*.md" --fix
此命令会：
  • 尽可能自动修复格式问题
  • 保留原始内容意图
  • 直接修改文件

Monitor for Issues

监控问题

Watch for:
  • Errors during the fix process
  • Files that couldn't be modified (permissions)
  • Any unexpected side effects
Document what was fixed automatically versus what remains.
注意以下情况：
  • 修复过程中的错误
  • 无法修改的文件（权限问题）
  • 任何意外副作用
记录自动修复的内容与剩余未修复的问题。

Phase 5: Manual Fixes

第五阶段：手动修复

Handle MD029 Issues

处理MD029问题

For remaining MD029 (ordered list item prefix) issues:
Load and consult 
references/MD029-Fix-Guide.md
for detailed guidance on:
  • Understanding the root cause: improper indentation of content between list items
  • Proper 4-space indentation for code blocks within lists
  • Indentation requirements for paragraphs, blockquotes, and nested content
  • Common mistakes and how to avoid them
  • Real-world examples showing before/after fixes
  • Alternative solutions and when to use them
Key insight: MD029 errors often occur when code blocks, paragraphs, or other content between list items lack proper indentation (typically 4 spaces), causing markdown parsers to break list continuity.
对于剩余的MD029（有序列表项前缀）问题：
加载并参考
references/MD029-Fix-Guide.md
获取详细指导，内容包括：
  • 理解根本原因：列表项之间的内容缩进不当
  • 列表中代码块的正确4空格缩进方式
  • 段落、块引用和嵌套内容的缩进要求
  • 常见错误及避免方法
  • 显示修复前后对比的实际示例
  • 替代解决方案及使用场景
关键要点：MD029错误通常发生在列表项之间的代码块、段落或其他内容缺少正确缩进（通常为4个空格）时，导致Markdown解析器中断列表连续性。

Apply Manual Corrections

应用手动修正

For issues not auto-fixed:
  • Open affected files
  • Apply fixes according to error type
  • Maintain consistency with existing markdown style
  • Verify fixes don't break content
对于无法自动修复的问题：
  • 打开受影响的文件
  • 根据错误类型应用修复
  • 与现有Markdown风格保持一致
  • 验证修复不会破坏内容

Phase 6: Verification & Reporting

第六阶段：验证与报告

Re-run Linter

重新运行代码检查

Confirm all issues are resolved:
bash
markdownlint-cli2 "**/*.md"
If no errors appear, linting is complete. If errors remain, document them for additional manual fixes.
确认所有问题已解决：
bash
markdownlint-cli2 "**/*.md"
如果没有错误出现，代码检查完成。如果仍有错误，记录这些错误以便进行额外的手动修复。

Generate Summary Report

生成总结报告

Provide a comprehensive summary including:
  1. Files Processed
    • Total count
    • List of files modified
    • Any files skipped or with errors
  2. Issues Fixed by Type
    • Count of each error type fixed
    • Auto-fixed vs. manually fixed
    • Special notes on MD029 fixes
  3. Remaining Issues (if any)
    • Error codes still present
    • Files requiring manual attention
    • Recommended next steps
  4. Completion Status
    • Confirmation of successful completion, or
    • Clear explanation of remaining work needed
    • Any error details with suggested solutions
提供全面的总结，包括：
  1. 处理的文件
    • 总数
    • 修改的文件列表
    • 任何跳过或有错误的文件
  2. 按类型修复的问题
    • 每种错误类型的修复数量
    • 自动修复与手动修复的对比
    • 关于MD029修复的特别说明
  3. 剩余问题（如有）
    • 仍存在的错误代码
    • 需要手动处理的文件
    • 建议的后续步骤
  4. 完成状态
    • 确认是否成功完成，或
    • 清晰说明剩余工作
    • 任何错误详情及建议解决方案

Key Principles

核心原则

Preserve Content Intent

保留内容意图

Always maintain the original meaning and structure of markdown content. Fix formatting without altering the author's intended message.
始终保持Markdown内容的原始含义和结构。修复格式时不要改变作者的预期信息。

Configuration Awareness

配置意识

Respect existing markdown configuration files. Don't override project-specific linting rules unless explicitly requested.
尊重现有的Markdown配置文件。除非明确要求，否则不要覆盖项目特定的代码检查规则。

Progressive Fixing

渐进式修复

Work from automatic fixes first, then manual fixes. This maximizes efficiency and reduces the risk of introducing errors.
先进行自动修复，再进行手动修复。这能最大化效率并减少引入错误的风险。

Comprehensive Reporting

全面报告

Provide clear, detailed reports at each phase so users understand:
  • What was found
  • What was fixed
  • What remains (if anything)
  • How to proceed
在每个阶段提供清晰、详细的报告，让用户了解：
  • 发现了什么
  • 修复了什么
  • 剩余内容（如有）
  • 如何继续

Error Handling

错误处理

When encountering errors:
  • Provide clear error messages
  • Suggest alternative approaches
  • Offer workarounds if primary methods fail
  • Never proceed without user confirmation on alternative paths
遇到错误时：
  • 提供清晰的错误信息
  • 建议替代方法
  • 如果主要方法失败，提供变通方案
  • 未经用户确认，绝不要在替代路径上继续

Common Scenarios

常见场景

Scenario 1: Clean Project Setup

场景1：全新项目配置

User request: "Set up markdown linting for my documentation"
Process:
  1. Install markdownlint-cli2
  2. Create 
    .markdownlint-cli2.jsonc
    with MD013 disabled
  3. Run diagnostic scan
  4. Execute auto-fix
  5. Report results
用户请求："为我的文档设置Markdown代码检查"
流程：
  1. 安装markdownlint-cli2
  2. 创建禁用MD013的
    .markdownlint-cli2.jsonc
  3. 运行诊断扫描
  4. 执行自动修复
  5. 报告结果

Scenario 2: Fix Existing Issues

场景2：修复现有问题

User request: "Fix all markdown linting errors in my project"
Process:
  1. Verify markdownlint-cli2 available
  2. Run comprehensive diagnostic
  3. Categorize and report issues
  4. Execute auto-fix
  5. Guide through remaining manual fixes
  6. Verify and report completion
用户请求："修复我项目中的所有Markdown代码检查错误"
流程：
  1. 验证markdownlint-cli2是否可用
  2. 运行全面诊断
  3. 分类并报告问题
  4. 执行自动修复
  5. 指导完成剩余手动修复
  6. 验证并报告完成情况

Scenario 3: MD029-Focused Fixing

场景3：聚焦MD029修复

User request: "I have ordered list numbering issues in my markdown files" or "My lists with code blocks are showing MD029 errors"
Process:
  1. Scan for MD029 errors specifically
  2. Attempt auto-fix
  3. For remaining issues, load MD029-Fix-Guide.md
  4. Guide through proper 4-space indentation for code blocks and content within lists
  5. Verify list continuity is maintained
  6. Report completion
用户请求："我的Markdown文件中有有序列表编号问题"或"包含代码块的列表显示MD029错误"
流程：
  1. 专门扫描MD029错误
  2. 尝试自动修复
  3. 对于剩余问题，加载MD029-Fix-Guide.md
  4. 指导列表中代码块和内容的正确4空格缩进方式
  5. 验证列表连续性是否保持
  6. 报告完成情况

Resources

资源

references/

references/

MD029-Fix-Guide.md

MD029-Fix-Guide.md

Comprehensive guide for handling MD029 (ordered list item prefix) errors, focusing on the root cause: improper indentation. This reference provides:
  • Explanation of why MD029 errors occur (content breaking list continuity)
  • Proper indentation rules: 4 spaces for code blocks, paragraphs, and other content
  • Indentation table showing requirements for different content types
  • Common mistakes with clear ❌ wrong vs ✅ correct examples
  • Real-world before/after examples
  • Alternative solutions and when to use markdownlint-disable comments
  • Best practices for maintaining list continuity
  • Verification steps
Load this file when MD029 errors persist after auto-fix, or when user needs guidance on fixing ordered list issues. The guide is particularly valuable when lists contain code blocks or mixed content.
处理MD029（有序列表项前缀）错误的综合指南，聚焦根本原因：缩进不当。本参考资料提供：
  • 解释MD029错误发生的原因（内容破坏列表连续性）
  • 正确的缩进规则：代码块、段落和其他内容使用4个空格
  • 显示不同内容类型缩进要求的表格
  • 常见错误的清晰❌错误示例与✅正确示例对比
  • 实际修复前后的示例
  • 替代解决方案及何时使用markdownlint-disable注释
  • 保持列表连续性的最佳实践
  • 验证步骤
当自动修复后仍存在MD029错误，或用户需要修复有序列表问题的指导时，加载此文件。当列表包含代码块或混合内容时，本指南尤其有用。

MD036-Guide.md

MD036-Guide.md

Comprehensive style guide for avoiding MD036 (no emphasis as heading) errors. This reference provides:
  • Clear explanation of the MD036 rule and why it matters
  • Wrong vs. correct examples showing bold text vs. proper heading syntax
  • Heading level hierarchy guidelines (h1 through h6)
  • Common violations to avoid when creating markdown files
  • Best practices for using headings vs. bold text
  • Quick checklist for markdown file creation and modification
Load this file when creating new markdown documentation or when encountering MD036 errors. Use as a reference to maintain consistent heading structure and avoid using bold text as heading substitutes.
避免MD036（不要用强调格式作为标题）错误的综合风格指南。本参考资料提供：
  • MD036规则的清晰解释及其重要性
  • 粗体文本与正确标题语法的错误示例与正确示例对比
  • 标题级别层次指南（h1至h6）
  • 创建Markdown文件时应避免的常见违规行为
  • 使用标题与粗体文本的最佳实践
  • Markdown文件创建和修改的快速检查清单
当创建新的Markdown文档或遇到MD036错误时，加载此文件。用作参考以保持一致的标题结构，避免使用粗体文本替代标题。