Markdownlint

Package manager detection

Before any operation, detect which package manager the project uses:

1. Check for lock files:

   • pnpm-lock.yaml → use pnpm
   • yarn.lock → use yarn
   • package-lock.json → use npm
   • bun.lockb → use bun

2. Check packageManager field in package.json:

   "packageManager": "[email protected]"
   

3. If no indicators, ask the user which package manager they prefer

Throughout this skill, commands use pnpm as examples. Replace with the detected package manager:

• pnpm add -D → npm install --save-dev / yarn add -D / bun add -d
• pnpm run → npm run / yarn run / bun run
• pnpm install → npm install / yarn install / bun install

Operation selection guide

Identify what the user needs and read the appropriate reference file:

• Initial Setup → Read references/setup.md

  • First time installation
  • Creating config files (.markdownlint.yaml, .markdownlintignore)
  • Adding npm scripts
  • Adding verification to AGENTS.md
  • Husky integration

• Modifying Rules → Read references/rules.md

  • Enabling/disabling specific rules
  • Configuring rule options (heading-style, ul-style, etc.)
  • Understanding rule names and codes (MD###)

• Updating Ignore Patterns → Read references/ignoring.md

  • Adding files/folders to .markdownlintignore
  • Gitignore-style pattern syntax
  • Verifying ignored files

• Fixing Violations → Read references/fixing.md

  • Understanding error messages
  • Auto-fix with --fix flag
  • Common violations (MD009, MD012, MD022, MD040, etc.)
  • Manual fixes for specific errors

• Integration Management → Read references/integration.md

  • Updating npm scripts
  • Modifying Husky hooks
  • CI/CD integration (GitHub Actions, GitLab CI)
  • VS Code extension setup

• Troubleshooting → Read references/troubleshooting.md

  • Too many errors
  • Files not being checked
  • Hook failures
  • Module not found errors
  • Performance issues

Quick reference: Common commands

# Install
pnpm add -D markdownlint markdownlint-cli

# Run linting
pnpm run lint:markdown

# Auto-fix issues
markdownlint '**/*.md' --fix

# Lint specific file
markdownlint README.md

# Lint specific directory
markdownlint 'docs/**/*.md'

Quick reference: Config file basics

.markdownlint.yaml in project root:

$schema: ./node_modules/markdownlint/schema/markdownlint-config-schema.json

# Disable a rule
line-length: false

# Enable a rule
no-duplicate-heading: true

# Configure a rule
heading-style:
  style: "atx"

.markdownlintignore in project root (gitignore syntax):

node_modules
dist/
build/
CHANGELOG.md

Key examples

Example 1: Basic setup

User: "Add markdownlint to my project"

Action: Read references/setup.md and follow Steps 1-9 for complete initial setup.

Example 2: Disable annoying rule

User: "Stop complaining about duplicate headings"

Action: Read references/rules.md → Removing rules section. Add no-duplicate-heading: false to .markdownlint.yaml.

Example 3: Fix many errors

User: "I have 50 markdown errors, fix them"

Action: Read references/fixing.md → Auto-fixing section. Run markdownlint '**/*.md' --fix, show diff, handle remaining errors.

Example 4: Ignore folder

User: "Don't lint the dist folder"

Action: Read references/ignoring.md. Add dist/ to .markdownlintignore.

Example 5: Add to CI

User: "Add markdown linting to GitHub Actions"

Action: Read references/integration.mdtions"

Action: Read references/integration.md → CI integration section. Create workflow file with pnpm setup and linting step.

Progressive workflow

For complex requests that span multiple operations:

1. Start with the main operation - Read the primary reference file first
2. Chain related operations - Read additional reference files as needed
3. Verify each step - Run commands to confirm changes work
4. Document what was done - Summarize changes for the user

Example: "Set up markdownlint with strict rules and CI"

• Read references/setup.md → complete initial setup
• Read references/rules.md → enable strict rules
• Read references/integration.md → add CI configuration
• Test all steps work together

When to use which reference

User mentions installation, setup, "add markdownlint": → references/setup.md

User mentions specific rules, MD codes, enabling/disabling: → references/rules.md

User mentions ignoring files, excluding folders: → references/ignoring.md

User has errors and wants to fix them: → references/fixing.md

User mentions npm scripts, husky, pre-commit, CI, GitHub Actions: → references/integration.md

User reports issues, things not working, errors: → references/troubleshooting.md

Default configuration philosophy

When setting up markdownlint, use this opinionated default configuration:

$schema: ./node_modules/markdownlint/schema/markdownlint-config-schema.json

line-length: false # Modern editors handle wrapping

Rationale: Start permissive, enable rules gradually. The line-length rule is disabled by default because:

• Modern editors and viewers handle text wrapping automatically
• Fixed line length creates unnecessary friction in most projects
• Semantic issues are more valuable to catch than presentation issues

Only add more rules if user explicitly requests them or if the project needs stricter validation.