Overview
Check and fix syntax, style, typos, and formatting issues in markdown files to ensure document quality.
Quick Start
Check a single markdown file:
python3 scripts/check_markdown.py path/to/file.md
Checklist
1. Syntax check
Heading hierarchy
- Check whether headings skip levels (such as jumping directly from H1 to H3)
- Verify ATX-style heading format (# Heading)
Link format
- Check for empty link text
[]() - Check for links missing a URL
[text]() - Check for spaces in link URLs
Code blocks
- Check whether code blocks specify a language
- Check whether code blocks are properly closed
List format
- Check for missing spaces after unordered list markers
- Check for missing spaces after ordered list numbers
2. Style check
Spaces and indentation
- Check for trailing spaces at the end of lines
- Check whether Tab indentation is used (spaces are recommended)
Paragraph spacing
- Check for more than 2 consecutive blank lines
3. Formatting check
Punctuation
- Check whether a space is missing after Chinese punctuation (if English follows)
- Check whether a space is missing between English and Chinese
Use the script
Run the check script:
python3 scripts/check_markdown.py <文件路径>
The script will output a detailed check report, including:
- ❌ Errors (must be fixed)
- ⚠️ Warnings (recommended to fix)
- ℹ️ Tips (optional to fix)
Manual check process
When you need to manually check a markdown file:
-
Read the file
- Use the Read tool to read the markdown file content
-
Perform the check
- Check whether the heading hierarchy is reasonable
- Check whether the link format is correct
- Check whether code blocks are complete
- Check whether the list format is standard
- Check whether spaces and indentation are consistent
- Check whether punctuation usage is standard
-
Generate a report
- List all discovered issues
- Classify by severity (errors, warnings, tips)
- Provide specific line numbers and content
-
Optional fixes
- If the user requests fixes, use the Edit tool to fix the issues
- After fixing, re-check to confirm the issues are resolved
Resources
scripts/check_markdown.py
Python script for automatically checking markdown files.
Features:
- Automatically detect syntax, style, and formatting issues
- Output a detailed check report
- Classify issues by severity
Usage:
python3 scripts/check_markdown.py path/to/file.md
Return values:
- Exit code 0: no errors
- Exit code 1: errors found