markdown-linting

name	markdown-linting
description	Lint and auto-fix markdown documentation using rumdl (Rust-based markdownlint). Use when creating or updating markdown files like README.md, CHANGELOG.md, or any .md documentation. Ensures consistent formatting with rules for line length, heading hierarchy, blank lines, and more.
metadata	{"version":"1.0.0","tool":"rumdl"}

Markdown Linting Skill

This skill helps you create well-formatted, linted markdown documentation using rumdl, a fast Rust-based markdown linter.

When to Use This Skill

Use this skill when you need to:

• Create new markdown documentation (README.md, CHANGELOG.md, guides, tutorials)
• Fix linting errors in existing markdown files
• Ensure markdown follows consistent formatting standards
• Auto-format markdown to meet style guidelines
• Set up markdown linting for a project

Quick Start

1. Check if rumdl is installed

rumdl version

If not installed, see references/REFERENCE.md for installation options.

2. Lint markdown files

# Check for issues
rumdl check README.md

# Auto-fix issues
rumdl fmt README.md

# Check all markdown in current directory
rumdl check .

3. Review and commit

git diff README.md
git add README.md
git commit -m "docs: Fix markdown linting issues"

Basic Workflow

Creating New Documentation

1. Start with a template - See references/TEMPLATES.md for common structures:

   • README.md template
   • CHANGELOG.md template
   • API documentation template
   • Tutorial template

2. Write your content - Focus on clarity and completeness:

   • Use descriptive headings
   • Include practical examples
   • Add code blocks with language specifiers
   • Keep paragraphs concise

3. Lint and fix - Run rumdl to ensure formatting compliance:

   rumdl fmt your-file.md
   

4. Review changes - Check the auto-fixes make sense:

   git diff your-file.md
   

Updating Existing Documentation

1. Make your changes - Edit the markdown file as needed

2. Run the linter - Check for issues:

   rumdl check your-file.md
   

3. Auto-fix if possible - Let rumdl fix common issues:

   rumdl fmt your-file.md
   

4. Manual fixes - Address any remaining issues the linter reports

5. Verify - Re-run the linter to confirm all issues are resolved:

   rumdl check your-file.md
   

Key Linting Rules

The skill uses a .rumdl.toml configuration with these key rules:

Line Length (MD013)

• Max 120 characters per line
• Break long lines at natural points (after sentences, before code blocks)

Blank Lines (MD022, MD032)

• Always add blank lines before and after:
  • Headings
  • Lists
  • Code blocks

Heading Hierarchy (MD001)

• Don't skip heading levels
• Correct: h1 → h2 → h3
• Incorrect: h1 → h3

Duplicate Headings (MD024)

• Allowed at different levels (siblings_only = true)
• You can reuse heading text in different sections

For detailed rule explanations and examples, see references/REFERENCE.md.

Common Commands

# Check single file
rumdl check README.md

# Check multiple files
rumdl check README.md CHANGELOG.md docs/*.md

# Check all markdown recursively
rumdl check .

# Auto-fix single file
rumdl fmt README.md

# Auto-fix all markdown
rumdl fmt .

# Check version
rumdl version

Configuration

Using the bundled configuration

This skill includes a .rumdl.toml with sensible defaults. Copy it to your project root:

cp .rumdl.toml /path/to/your/project/

Custom configuration

Create your own .rumdl.toml in your project root:

[MD013]
line-length = 100  # Change from default 120

[MD024]
siblings-only = true

Converting from markdownlint

If you have an existing .markdownlintrc.json:

rumdl import .markdownlintrc.json --output .rumdl.toml

Installation Options

Option 1: pip3 (Recommended)

pip3 install rumdl

Option 2: Bundled Binary

Use the bundled binary and installation script:

# From this skill directory
cd scripts
./install-rumdl.sh

This installs to ~/.local/bin/rumdl.

Option 3: Direct Binary Usage

Use the bundled binary directly without installation:

# From this skill directory
./scripts/rumdl check /path/to/your/file.md

For detailed installation instructions and troubleshooting, see references/REFERENCE.md.

Document Templates

See references/TEMPLATES.md for complete templates:

• README.md - Project overview and documentation
• CHANGELOG.md - Version history following Keep a Changelog format
• API Documentation - For libraries and APIs
• Contributing Guide - For open-source projects
• Tutorial - Step-by-step learning content

Troubleshooting

Linter reports issues I disagree with

If a specific line should ignore a rule, add a comment:

<!-- markdownlint-disable MD013 -->
This very long line will not trigger the line length rule.
<!-- markdownlint-enable MD013 -->

Auto-fix made unexpected changes

Review changes with git diff before committing. If needed, revert and fix manually:

git checkout -- file.md

rumdl command not found

• Ensure ~/.local/bin is in your PATH
• Or use the bundled binary: ./scripts/rumdl
• Or install via pip3: pip3 install rumdl

See references/REFERENCE.md for more troubleshooting tips.

Best Practices

1. Lint early and often - Run rumdl check as you write
2. Use templates - Start with proven structures from references/TEMPLATES.md
3. Keep lines readable - Break at natural points, not just at 120 chars
4. Use blank lines - They improve readability
5. Specify code block languages - Always add the language after triple backticks
6. Review auto-fixes - Ensure they maintain your intended meaning

Tips for AI Assistants

When helping users with markdown documentation:

1. Always run the linter after creating or modifying markdown files
2. Use auto-fix when possible - rumdl fmt handles most issues automatically
3. Check templates first - Refer to references/TEMPLATES.md for structure
4. Focus on content first - Let rumdl handle formatting details
5. Verify the result - Run rumdl check to confirm no linting errors remain

Additional Resources

• references/REFERENCE.md - Detailed linting rules, configuration, and troubleshooting
• references/TEMPLATES.md - Complete document templates for common use cases
• Keep a Changelog - Standard for CHANGELOG.md format
• Semantic Versioning - Versioning standard for changelogs