dev-markdown-lint

Check markdown files for formatting and style issues using markdownlint-cli2.

When to use this skill:

• Before committing changes to markdown files
• After creating or updating lessons, READMEs, or documentation
• When CI markdown linting checks fail
• To ensure consistent markdown style across the project

AI auto-invocation:

The model should automatically invoke this skill:

• After creating/updating markdown files — Run npx markdownlint-cli2 "**/*.md" to check
• Before git commits touching markdown — Verify no linting errors
• If errors found — Attempt auto-fix with --fix flag first, then fix remaining errors manually
• Always verify after fixes — Re-run to ensure all errors resolved

Arguments

• --fix (optional): Automatically fix auto-fixable issues

If no arguments provided, runs in check-only mode.

What it does

1. Check mode (default): Reports errors without modifying files
2. Fix mode (--fix): Automatically fixes issues like:
   • Missing blank lines around headings
   • Inconsistent list formatting
   • Trailing whitespace
   • Some language tag issues (if the content type is obvious)

Note: Not all errors are auto-fixable. Some require manual intervention (like choosing the right language tag for a code block).

Configuration

The project uses .markdownlint-cli2.jsonc for configuration:

Strict rules (must follow):

• MD040: Code blocks MUST have language tags (```text, ```c, ```bash, etc.)
• MD060: Tables must have consistent column alignment

Lenient rules:

• Line length (MD013): Disabled — lessons need flexibility
• Blank lines (MD031/MD032): Lenient — formatting varies by context
• Duplicate headings (MD024): Allowed at different levels
• HTML (MD033): Allowed when needed for formatting

CRITICAL — Configuration is non-negotiable:

• NEVER disable or remove lint rules to make errors pass
• NEVER relax existing rules (e.g., turning MD040 from error to warning)
• NEVER modify .markdownlint-cli2.jsonc to bypass validation
• NEVER remove or disable the CI workflow (.github/workflows/markdown-lint.yml)

If linting fails, fix the markdown — do not weaken the linter. Quality checks protect learning quality for all users.

Common errors and fixes

MD040: Missing language tag on code block

Error:

README.md:45 MD040/fenced-code-language Fenced code blocks should have a language specified

Problem: Code block missing language identifier:

```
some code here
```

Fix: Add appropriate language tag:

```c
some code here
```

Common tags:

• bash — Shell commands, scripts
• c — C code
• text — Plain text, output, diagrams, directory trees
• markdown — Markdown examples
• cmake — CMake files
• hlsl — Shader code

Nested code blocks: When showing a code block inside a code block (like in documentation), use 4 backticks for the outer fence:

````markdown
# Example
```c
code here
```
````

MD060: Table columns should have consistent alignment

Error:

README.md:80 MD060/table-column-count Table row column count

Problem: Table rows have different numbers of columns, or alignment is inconsistent.

Fix: Ensure all rows have the same number of columns:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Running the skill

Check for errors

/dev-markdown-lint

Or manually:

npx markdownlint-cli2 "**/*.md"

Auto-fix issues

/dev-markdown-lint --fix

Or manually:

npx markdownlint-cli2 --fix "**/*.md"

Workflow

Before committing

Always run markdown linting before creating a commit with markdown changes:

npx markdownlint-cli2 "**/*.md"

If errors are found:

1. Try auto-fix: npx markdownlint-cli2 --fix "**/*.md"
2. Review remaining errors and fix manually
3. Re-run to verify: npx markdownlint-cli2 "**/*.md"

In CI

The .github/workflows/markdown-lint.yml workflow runs automatically on:

• Pull requests touching markdown files
• Pushes to main with markdown changes

If CI fails, run the linter locally to see the errors.

Implementation

When this skill is invoked:

1. Parse arguments:

   • Check if --fix flag is present
   • Default to check-only mode

2. Run markdownlint-cli2:

   bashCopy

   npx markdownlint-cli2 [--fix] "**/*.md"
   

3. Interpret results:

   • Exit code 0: All files pass ✓
   • Exit code 1: Errors found

4. Report to user:

   • If errors found: List them with file:line and error code
   • Suggest fixes for common errors (MD040, MD060)
   • If --fix was used, report what was auto-fixed
   • Show command to re-run manually if needed

5. Next steps:

   • If errors remain after auto-fix, guide user to fix manually
   • Suggest running the skill again to verify fixes

Tips

• Always add language tags to code blocks — it improves readability and syntax highlighting
• Use text for non-code blocks like output, diagrams, directory trees
• Nested code blocks require different fence lengths (outer uses 4+ backticks)
• Run before committing to catch issues early
• Auto-fix first then handle remaining errors manually
• Check the config (.markdownlint-cli2.jsonc) to understand which rules are enabled

Example output

All files pass:

markdownlint-cli2 v0.20.0 (markdownlint v0.40.0)
Finding: **/*.md
Linting: 20 file(s)
Summary: 0 error(s)

Errors found:

markdownlint-cli2 v0.20.0 (markdownlint v0.40.0)
Finding: **/*.md
Linting: 20 file(s)
README.md:45 MD040/fenced-code-language Fenced code blocks should have a language specified
lessons/math/01-vectors/README.md:180 MD040/fenced-code-language Fenced code blocks should have a language specified
common/math/DESIGN.md:85 MD040/fenced-code-language Fenced code blocks should have a language specified
Summary: 3 error(s)

Related documentation

• markdownlint rules
• Project config: .markdownlint-cli2.jsonc
• CI workflow: .github/workflows/markdown-lint.yml
• CLAUDE.md section on markdown linting