Menu
Fix markdown linting errors in documentation files
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Conduct thorough code reviews for pull requests and pre-commit changes
Run comprehensive project health checks including code quality, documentation, git status, and project structure
Check CI/CD workflow status and troubleshoot failing checks in GitHub Actions
Initialize .docent/ directory structure and configuration for a new project
Comprehensive guide for AI agents on proactive documentation capture using /docent:tell
Migrate a docent v0.9 project to v1.0 skills-based architecture
| name | fix-markdown-lint |
| description | Fix markdown linting errors in documentation files |
| group | docent |
| keywords | ["markdown","linting","quality","documentation"] |
| version | 1.0.0 |
| author | @tnez |
Purpose: Fix markdown linting errors in documentation files Owner: Development Team Last Updated: 2025-10-17 Frequency: Before releases, when CI lint workflow fails
This runbook provides procedures for fixing markdown linting errors using markdownlint-cli2. Our CI/CD runs markdown linting on all *.md files, and errors will block merges to main.
Script Reference: ../../scripts/lint-markdown.sh
Expected duration: 5-10 minutes for most fixes (auto-fix handles ~95% of errors)
npm - Node.js package managernpm install)Before starting, ensure:
npm --versionls node_modules/markdownlint-cli2Purpose: Understand what errors exist
Commands:
# Run markdown linter (shows all errors)
npm run lint:md
# Or use the script directly:
scripts/lint-markdown.sh
# Count total errors
npm run lint:md 2>&1 | grep -c "MD0"
# See errors for specific file
scripts/lint-markdown.sh docs/guides/getting-started.md
Validation:
If step fails:
npm installPurpose: Automatically fix ~95% of markdown linting errors
Commands:
# Auto-fix all fixable errors
npm run lint:md -- --fix
# Or use the script directly:
scripts/lint-markdown.sh --fix
# Check remaining errors
npm run lint:md
Validation:
git statusCommon Auto-Fixed Errors:
If step fails:
git diff to understand what changedPurpose: Handle errors that can't be auto-fixed
Common Manual Fixes:
Error:
file.md:193:1 MD029/ol-prefix Ordered list item prefix [Expected: 1; Actual: 2; Style: 1/1/1]
Cause: Inconsistent ordered list numbering style
Fix Options:
Option A: Use sequential numbering (1, 2, 3)
1. First item
2. Second item
3. Third item
Option B: Use all 1's (lazy numbering)
1. First item
1. Second item
1. Third item
Commands:
# Find the problematic file and line
npm run lint:md 2>&1 | grep MD029
# Edit the file
$EDITOR docs/guides/getting-started.md
# Go to line number shown in error
# Fix numbering to be consistent
# Save and re-check
npm run lint:md
Validation:
Error:
file.md:45 MD013/line-length Line length [Expected: 80; Actual: 120]
Cause: Line exceeds 80 characters (or configured limit)
Fix:
# View the long line
sed -n '45p' docs/guides/getting-started.md
# Edit and break into multiple lines
$EDITOR docs/guides/getting-started.md
# For code blocks, this rule is often ignored - check if it should be
Note: Often better to configure .markdownlintrc to ignore line length in code blocks
Error:
file.md:67 MD040/fenced-code-language Fenced code blocks should have a language specified
Cause: Code fence without language specifier
Fix:
# Before (no language)
code here
# After (with language)
```bash
code here
**Common Languages:**
- `bash` - Shell commands
- `javascript` / `typescript` - JS/TS code
- `json` - JSON config
- `markdown` - Markdown examples
- `text` - Plain text output
---
### Step 4: Verify All Errors Fixed
**Purpose:** Confirm linting passes
**Commands:**
```bash
# Run linter
npm run lint:md
# Check exit code
echo $?
# Expected: 0 (success)
# Verify in CI (after commit)
gh run list --workflow=lint.yml --limit 3
Validation:
npm run lint:md shows "0 error(s)"git status shows modified filesIf step fails:
Purpose: Understand what changed before committing
Commands:
# See all changes
git diff
# Review specific file
git diff docs/guides/getting-started.md
# Check summary of changes
git diff --stat
Validation:
Common Changes to Expect:
If step fails:
git checkout -- <file>Purpose: Save linting fixes
Commands:
# Stage all markdown files
git add '*.md' 'docs/**/*.md'
# Or stage specific files
git add README.md docs/guides/getting-started.md
# Commit with clear message
git commit -m "chore: fix markdown linting errors
- Auto-fix whitespace and formatting issues
- Fix ordered list numbering consistency
- All lint checks now passing"
# Verify commit
git log -1 --stat
Validation:
If step fails:
git commit --amend to fix messagegit reset HEAD~1 to undo and restartAfter completing all steps, verify:
Local Lint Passes:
npm run lint:md
# Expected: "Summary: 0 error(s)"
Exit Code is 0:
npm run lint:md && echo "PASS" || echo "FAIL"
# Expected: "PASS"
Files Committed:
git log -1 --name-only
# Expected: Shows markdown files changed
CI Will Pass:
# After pushing
gh run watch
# Expected: Lint workflow succeeds
Symptoms:
Resolution:
# Focus on one directory at a time
npx markdownlint-cli2 'docs/guides/**/*.md' --fix
npx markdownlint-cli2 'docs/rfcs/**/*.md' --fix
# Or one file at a time
npx markdownlint-cli2 docs/guides/getting-started.md --fix
# Check progress
npm run lint:md 2>&1 | grep -c "MD0"
Symptoms:
Resolution:
# Revert changes
git checkout -- docs/guides/problematic-file.md
# Fix manually without auto-fix
$EDITOR docs/guides/problematic-file.md
# Check specific file
npx markdownlint-cli2 docs/guides/problematic-file.md
Prevention:
git diff before committingSymptoms:
Resolution:
# Get rule documentation URL
npm run lint:md 2>&1 | grep -A 1 "MD032"
# Shows link to: https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md032.md
# Or search for rule:
# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
Common Rules:
Symptoms:
npm run lint:md passes locallyResolution:
# Ensure you're linting the same files as CI
npm run lint:md
# Check if .gitignore is excluding files CI sees
git ls-files '*.md' | wc -l
# Verify no unstaged changes
git status
# Try exact CI command
npx markdownlint-cli2 '**/*.md' '!node_modules' '!lib'
Common Causes:
.gitignore differencesEscalate if:
Escalation Contact:
After completion:
# Check errors
npm run lint:md
# Auto-fix everything
npm run lint:md -- --fix
# Fix specific directory
npx markdownlint-cli2 'docs/guides/**/*.md' --fix
# Fix specific file
npx markdownlint-cli2 docs/guides/file.md --fix
# Count remaining errors
npm run lint:md 2>&1 | grep -c "MD0"
# Commit fixes
git add '*.md' 'docs/**/*.md'
git commit -m "chore: fix markdown linting errors"
Linting configuration in package.json scripts:
{
"scripts": {
"lint:md": "markdownlint-cli2 '**/*.md' '!node_modules' '!lib'"
}
}
This project uses the default markdownlint rules. If you need to customize rules, you can create a .markdownlintrc or .markdownlint.json file in the project root.
Important Notes:
git diff before committingdocs/.journal/ are gitignored - lint errors OKGotchas:
Related Procedures:
| Date | Author | Changes |
|---|---|---|
| 2025-10-17 | @tnez | Initial creation |