๐๐ผ๐ ๐๐ผ ๐ฅ๐ฒ๐ฑ๐๐ฐ๐ฒ ๐ ๐ฎ๐ฟ๐ธ๐ฑ๐ผ๐๐ป๐น๐ถ๐ป๐ ๐ฉ๐ถ๐ผ๐น๐ฎ๐๐ถ๐ผ๐ป๐ ๐ถ๐ป ๐๐-๐๐ฒ๐ป๐ฒ๐ฟ๐ฎ๐๐ฒ๐ฑ ๐ ๐ฎ๐ฟ๐ธ๐ฑ๐ผ๐๐ป
AI agents like Claude Code or GitHub Copilot often create Markdown files with style errors. These errors trigger warnings in markdownlint.
Common errors include:
- MD022: Missing blank lines around headings.
- MD032: Missing blank lines around lists.
- MD058: Missing blank lines around tables.
- MD013: Lines that are too long.
- MD036: Using bold text instead of a proper heading.
- MD009: Extra spaces at the end of lines.
- MD012: Too many blank lines in a row.
You can fix these errors using two methods.
- Adjust your settings
You can relax the rules in your .markdownlint.json file. This makes the tool less strict. For example, you can increase the line length limit from 80 to 120 characters. You can also tell the tool to ignore tables or code blocks.
- Use instruction files
You can tell AI agents how to write Markdown before they start. Use files like CLAUDE.md or AGENTS.md to give them specific rules.
Include these details in your instructions:
- Add blank lines before and after headings.
- Add blank lines before and after lists.
- Keep lines under 120 characters.
- Use real headings instead of just bold text.
Adding examples of good and bad Markdown helps the AI follow these rules better.
Where to put instruction files:
- Claude Code: Use CLAUDE.md in your project root.
- General AI Agents: Use AGENTS.md in your project root.
- GitHub Copilot: Use .github/copilot-instructions.md.
- Kiro: Use .kiro/steering/ files or AGENTS.md.
You cannot stop every error, but using both methods works well together.
Source: https://dev.to/satoshi256kbyte/how-to-reduce-markdownlint-violations-in-ai-generated-markdown-2haj
Optional learning community: https://t.me/GyaanSetuAi