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

1. Check packageManager field in package.json:

``json "packageManager": "[email protected]" ``

1. 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](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](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](references/ignoring.md)

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

• Fixing Violations → Read [references/fixing.md](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](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](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](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](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](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](references/ignoring.md). Add dist/ to .markdownlintignore.

Example 5: Add to CI

User: "Add markdown linting to GitHub Actions"

Action: Read [references/integration.md](references/integration.md)tions"

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](references/setup.md) → complete initial setup
• Read [references/rules.md](references/rules.md) → enable strict rules
• Read [references/integration.md](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](references/setup.md)

User mentions specific rules, MD codes, enabling/disabling: → [references/rules.md](references/rules.md)

User mentions ignoring files, excluding folders: → [references/ignoring.md](references/ignoring.md)

User has errors and wants to fix them: → [references/fixing.md](references/fixing.md)

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

User reports issues, things not working, errors: → [references/troubleshooting.md](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.