Runbook: Fix Markdown Linting

Purpose: Fix markdown linting errors in documentation files Owner: Development Team Last Updated: 2025-10-17 Frequency: Before releases, when CI lint workflow fails

Overview

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)

Prerequisites

Required Tools

• npm - Node.js package manager
• Project dependencies installed (npm install)

Required Access

• Write access to fix files locally

Pre-Flight Checklist

Before starting, ensure:

• You have npm installed: npm --version
• Project dependencies installed: ls node_modules/markdownlint-cli2
• You are in the project directory

Procedure

Step 1: Check Current Lint Status

Purpose: 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:

• Output shows list of files with errors
• Error codes displayed (MD032, MD031, MD029, etc.)
• Line numbers provided for each error

If step fails:

• If command not found: npm install
• If no errors: linting already passing!

Step 2: Auto-Fix Errors

Purpose: 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:

• Most errors are automatically fixed
• Remaining errors are typically MD029 (ordered list numbering)
• Modified files appear in git status

Common Auto-Fixed Errors:

• MD032: Blank lines around lists (adds blank lines)
• MD031: Blank lines around code fences (adds blank lines)
• MD009: Trailing spaces (removes them)
• MD010: Hard tabs (converts to spaces)
• MD047: Files end with newline (adds newline)

If step fails:

• No failures expected - auto-fix is safe
• Review changes with git diff to understand what changed

Step 3: Fix Remaining Errors Manually

Purpose: Handle errors that can't be auto-fixed

Common Manual Fixes:

MD029: Ordered List Numbering

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:

• MD029 errors are gone
• List renders correctly in markdown preview

MD013: Line Too Long

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

MD040: Fenced Code Language

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)

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:

# 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)"
• Exit code is 0
• git status shows modified files

If step fails:

• Review remaining errors
• Repeat Steps 2-3
• Check for typos in fixes

Step 5: Review Changes

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:

• Changes are only whitespace/formatting
• No content was accidentally modified
• Lists still make sense

Common Changes to Expect:

• Blank lines added before/after lists
• Blank lines added before/after code fences
• Trailing spaces removed
• List numbering made consistent

If step fails:

• If unwanted changes: git checkout -- <file>
• Re-run auto-fix and be more careful with manual edits

Step 6: Commit Fixes

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:

• Commit contains only markdown files
• Commit message follows conventions
• Changes are reasonable in size

If step fails:

• Use git commit --amend to fix message
• Use git reset HEAD~1 to undo and restart

Validation

After completing all steps, verify:

1. Local Lint Passes:

``bash npm run lint:md # Expected: "Summary: 0 error(s)" ``

1. Exit Code is 0:

``bash npm run lint:md && echo "PASS" || echo "FAIL" # Expected: "PASS" ``

1. Files Committed:

``bash git log -1 --name-only # Expected: Shows markdown files changed ``

1. CI Will Pass:

``bash # After pushing gh run watch # Expected: Lint workflow succeeds ``

Troubleshooting

Common Issues

Issue 1: Too Many Errors (> 100)

Symptoms:

• Auto-fix leaves many errors
• Errors span many files

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"

Issue 2: Auto-Fix Breaks Formatting

Symptoms:

• Lists are malformed after auto-fix
• Code blocks have extra blank lines

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:

• Review git diff before committing
• Test one file first before bulk auto-fix

Issue 3: Error Code Not Clear

Symptoms:

• Don't understand what MD### means
• Not sure how to fix

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:

• MD009: No trailing spaces
• MD010: No hard tabs
• MD013: Line length
• MD029: Ordered list prefixes
• MD031: Fenced code blocks blank lines
• MD032: Lists blank lines
• MD040: Fenced code language
• MD047: Files end with newline

Issue 4: Linting Passes Locally, Fails in CI

Symptoms:

• npm run lint:md passes locally
• CI lint workflow fails

Resolution:

# 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:

• Unstaged markdown files
• .gitignore differences
• Different markdownlint-cli2 versions

When to Escalate

Escalate if:

• Auto-fix produces invalid markdown
• Linting rules conflict with project style
• CI failing but local passing consistently
• Need to change linting configuration

Escalation Contact:

• Repository maintainer
• DevOps team (for CI issues)

Post-Procedure

After completion:

• All markdown files pass linting
• Changes committed and pushed
• CI lint workflow passes
• No documentation rendering issues

Quick Reference

Essential Commands

# 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"

Configuration

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.

Notes

Important Notes:

• Auto-fix is safe - it won't change content, only formatting
• Always review git diff before committing
• Journal files in docs/.journal/ are gitignored - lint errors OK
• Some errors can't be auto-fixed (MD029 ordered lists)

Gotchas:

• MD029 (ordered list) requires manual fix - choose consistent style
• Auto-fix adds a LOT of blank lines - this is correct!
• Markdown rendering may differ from linting rules - trust the linter
• CI runs on ALL markdown including those you didn't change

Related Procedures:

• [CI/CD Health Check](./ci-cd-health-check.md) - for checking lint workflow status
• [Prepare Release](./prepare-release.md) - linting is part of release preparation

Revision History