markdown-linting — Skillopedia

Markdown Linting This skill provides comprehensive guidance for markdown linting using , the industry-standard markdown linter that can be used in any project. Table of Contents - Overview - When to Use This Skill - Markdown Flavors - First Use: Installation and Setup - Setting Up Markdown Linting in Your Repo - Quick Start - Unified Tooling Architecture - CRITICAL: Configuration Policy - CRITICAL: NO AUTOMATED SCRIPTS - Running Linting Locally - Intelligent Fix Handling - VS Code Extension Setup (Optional/Advanced) - GitHub Actions Integration (Optional/Advanced) - Customizing Rules (Require…

| xargs markdownlint-cli2\n```\n\n**Benefits:**\n\n- Faster than linting all files\n- Useful for large repositories\n- Focus on recent changes\n\n### 3. CI/CD Enhancements\n\n#### Progressive Enforcement\n\n**Concept:** Fail fast on critical rules, warn on others\n\n```yaml\n# .github/workflows/markdown-lint.yml\n- name: Check critical rules (fail on error)\n uses: DavidAnson/markdownlint-cli2-action@v22\n with:\n config: .markdownlint-cli2-critical.jsonc\n globs: '**/*.md'\n\n- name: Check all rules (warn only)\n uses: DavidAnson/markdownlint-cli2-action@v22\n continue-on-error: true\n with:\n globs: '**/*.md'\n```\n\n**Benefits:**\n\n- Don't block PRs on minor issues\n- Gradually increase standards\n- Educate without frustrating\n\n## Implementation Guidance\n\nWhen adding new automation scripts to your project:\n\n1. **Follow established patterns:**\n - Use consistent naming conventions\n - Include comprehensive error handling\n - Provide clear, actionable error messages\n\n2. **Document thoroughly:**\n - Add usage instructions to script comments\n - Update this README.md with script details (or your project's docs)\n - Provide examples and expected output\n\n3. **Test before committing:**\n - Verify scripts work in target environments\n - Test edge cases and error conditions\n - Ensure cross-platform compatibility (if needed)\n\n4. **Make executable:**\n - Set execute permissions: `chmod +x scripts/script-name.sh`\n - Add shebang line: `#!/bin/bash` or `#!/usr/bin/env python3`\n\n5. **Document in your project:**\n - Note any new dependencies\n - Document prerequisites or setup required\n - Update any relevant documentation\n\n## Resources\n\n- **markdownlint-cli2 Documentation:** [github.com/DavidAnson/markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2)\n- **Husky (Git hooks):** [typicode.github.io/husky](https://typicode.github.io/husky)\n- **lint-staged:** [github.com/okonet/lint-staged](https://github.com/okonet/lint-staged)\n- **GitHub Actions:** [docs.github.com/actions](https://docs.github.com/en/actions)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":7242,"content_sha256":"0dd011b66e75fea691592de483c9788eb4a4025c77010bda90ac39ca5d6f87c6"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Markdown Linting","type":"text"}]},{"type":"paragraph","content":[{"text":"This skill provides comprehensive guidance for markdown linting using ","type":"text"},{"text":"markdownlint-cli2","type":"text","marks":[{"type":"code_inline"}]},{"text":", the industry-standard markdown linter that can be used in any project.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Table of Contents","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Overview","type":"text","marks":[{"type":"link","attrs":{"href":"#overview","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When to Use This Skill","type":"text","marks":[{"type":"link","attrs":{"href":"#when-to-use-this-skill","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Markdown Flavors","type":"text","marks":[{"type":"link","attrs":{"href":"#markdown-flavors","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"First Use: Installation and Setup","type":"text","marks":[{"type":"link","attrs":{"href":"#first-use-installation-and-setup","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Setting Up Markdown Linting in Your Repo","type":"text","marks":[{"type":"link","attrs":{"href":"#setting-up-markdown-linting-in-your-repo","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Quick Start","type":"text","marks":[{"type":"link","attrs":{"href":"#quick-start","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Unified Tooling Architecture","type":"text","marks":[{"type":"link","attrs":{"href":"#unified-tooling-architecture","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CRITICAL: Configuration Policy","type":"text","marks":[{"type":"link","attrs":{"href":"#critical-configuration-policy","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CRITICAL: NO AUTOMATED SCRIPTS","type":"text","marks":[{"type":"link","attrs":{"href":"#critical-no-automated-scripts","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Running Linting Locally","type":"text","marks":[{"type":"link","attrs":{"href":"#running-linting-locally","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Intelligent Fix Handling","type":"text","marks":[{"type":"link","attrs":{"href":"#intelligent-fix-handling","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"VS Code Extension Setup (Optional/Advanced)","type":"text","marks":[{"type":"link","attrs":{"href":"#vs-code-extension-setup-optionaladvanced","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitHub Actions Integration (Optional/Advanced)","type":"text","marks":[{"type":"link","attrs":{"href":"#github-actions-integration-optionaladvanced","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Customizing Rules (Requires Approval)","type":"text","marks":[{"type":"link","attrs":{"href":"#customizing-rules-requires-approval","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Troubleshooting","type":"text","marks":[{"type":"link","attrs":{"href":"#troubleshooting","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Best Practices","type":"text","marks":[{"type":"link","attrs":{"href":"#best-practices","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Resources","type":"text","marks":[{"type":"link","attrs":{"href":"#resources","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Evaluation Scenarios","type":"text","marks":[{"type":"link","attrs":{"href":"#evaluation-scenarios","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Multi-Model Testing Notes","type":"text","marks":[{"type":"link","attrs":{"href":"#multi-model-testing-notes","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Version History","type":"text","marks":[{"type":"link","attrs":{"href":"#version-history","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Last Updated","type":"text","marks":[{"type":"link","attrs":{"href":"#last-updated","title":null}}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"This tooling enables enforcement of strict markdown quality standards through automated linting. Markdown files can be validated using ","type":"text"},{"text":"markdownlint-cli2","type":"text","marks":[{"type":"code_inline"}]},{"text":" with a unified tooling approach that ensures zero configuration drift across VS Code, CLI, and CI/CD environments.","type":"text"}]},{"type":"paragraph","content":[{"text":"Core Philosophy:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Single source of truth: ","type":"text"},{"text":".markdownlint-cli2.jsonc","type":"text","marks":[{"type":"code_inline"}]},{"text":" contains all configuration (rules, ignores, options)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Unified tooling: Same ","type":"text"},{"text":"markdownlint-cli2","type":"text","marks":[{"type":"code_inline"}]},{"text":" engine everywhere (VS Code, CLI, CI/CD)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Strict enforcement: Fix content to comply with rules, not rules to accommodate content","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Quality-first: Linting rules are intentional and enforce documentation quality","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When to Use This Skill","type":"text"}]},{"type":"paragraph","content":[{"text":"This skill should be used when:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User encounters markdown linting errors (MD001, MD013, MD033, etc.)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User asks about markdown validation, formatting, or quality standards","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User needs to configure ","type":"text"},{"text":".markdownlint-cli2.jsonc","type":"text","marks":[{"type":"code_inline"}]},{"text":" (rules, ignores, or options)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User asks about configuration file setup or structure","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User wants to set up VS Code markdown linting extension","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User needs to troubleshoot markdown linting issues","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User asks how to run markdown linting locally","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User wants to understand GitHub Actions markdown validation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User is working with markdown files and needs quality guidance","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Markdown Flavors","type":"text"}]},{"type":"paragraph","content":[{"text":"markdownlint-cli2 supports multiple markdown flavors. By default, it validates GitHub Flavored Markdown (GFM), which is recommended for most projects.","type":"text"}]},{"type":"paragraph","content":[{"text":"Supported Flavors:","type":"text","marks":[{"type":"strong"}]}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Flavor","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":"center"},"content":[{"type":"paragraph","content":[{"text":"Default","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Best For","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"GFM","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":"center"},"content":[{"type":"paragraph","content":[{"text":"✓","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"GitHub repos, most web projects","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"CommonMark","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":"center"},"content":[{"type":"paragraph"}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Maximum portability, strict compliance","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Quick Guidance:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use GFM (default)","type":"text","marks":[{"type":"strong"}]},{"text":" for GitHub repos, typical web projects, and when you need tables/task lists","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use CommonMark","type":"text","marks":[{"type":"strong"}]},{"text":" for cross-platform publishing or strict standards compliance","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For detailed flavor guidance","type":"text","marks":[{"type":"strong"}]},{"text":", see the dedicated reference files:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Flavors Overview","type":"text","marks":[{"type":"link","attrs":{"href":"references/flavors/overview.md","title":null}}]},{"text":" - Comparison and selection guidance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GFM Configuration","type":"text","marks":[{"type":"link","attrs":{"href":"references/flavors/gfm.md","title":null}}]},{"text":" - GitHub Flavored Markdown (default)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CommonMark Configuration","type":"text","marks":[{"type":"link","attrs":{"href":"references/flavors/commonmark.md","title":null}}]},{"text":" - Strict base specification","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Flavor-Sensitive Rules:","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Some rules only apply to specific flavors. See ","type":"text"},{"text":"Markdownlint Rules Reference","type":"text","marks":[{"type":"link","attrs":{"href":"references/markdownlint-rules.md","title":null}}]},{"text":" for rules tagged with their flavor compatibility.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"First Use: Installation and Setup","type":"text"}]},{"type":"paragraph","content":[{"text":"If this is your first time setting up markdown linting","type":"text","marks":[{"type":"strong"}]},{"text":", see the comprehensive installation guide:","type":"text"}]},{"type":"paragraph","content":[{"text":"Installation and Setup Guide","type":"text","marks":[{"type":"link","attrs":{"href":"references/installation-setup.md","title":null}},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"This guide covers:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prerequisites (Node.js/npm)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Detection of existing setup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Two approaches: npx (zero setup) vs local install (full features)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Configuration file creation (","type":"text"},{"text":".markdownlint-cli2.jsonc","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Configuring rules, ignores, and options in one file","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verification steps","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Troubleshooting setup issues","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Quick detection check:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Check if you're already set up\nls .markdownlint-cli2.jsonc # Configuration exists?\nnpm list markdownlint-cli2 # Package installed?\ncat package.json | grep \"lint:md\" # Scripts configured?","type":"text"}]},{"type":"paragraph","content":[{"text":"If any of these are missing, follow the ","type":"text"},{"text":"Installation and Setup Guide","type":"text","marks":[{"type":"link","attrs":{"href":"references/installation-setup.md","title":null}}]},{"text":" first.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Setting Up Markdown Linting in Your Repo","type":"text"}]},{"type":"paragraph","content":[{"text":"This section provides a complete guide for setting up markdown linting from scratch in any repository.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Prerequisites","type":"text"}]},{"type":"paragraph","content":[{"text":"Node.js 20+","type":"text","marks":[{"type":"strong"}]},{"text":" is required. Install via ","type":"text"},{"text":"fnm","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/Schniz/fnm","title":null}}]},{"text":" (recommended):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Windows (PowerShell as Admin)\nwinget install Schniz.fnm\n\n# macOS/Linux\ncurl -fsSL https://fnm.vercel.app/install | bash","type":"text"}]},{"type":"paragraph","content":[{"text":"Then in Git Bash, add to ","type":"text"},{"text":"~/.bashrc","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"eval \"$(fnm env --use-on-cd --shell bash)\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Install Node:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"fnm install 24 && fnm default 24","type":"text"}]},{"type":"paragraph","content":[{"text":"Why fnm?","type":"text","marks":[{"type":"strong"}]},{"text":" Unlike nvm-windows, fnm works natively in Git Bash without ","type":"text"},{"text":"silent output bugs","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/coreybutler/nvm-windows/wiki/Common-Issues","title":null}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1: Create Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"Create ","type":"text"},{"text":".markdownlint-cli2.jsonc","type":"text","marks":[{"type":"code_inline"}]},{"text":" in your repo root:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"jsonc"},"content":[{"text":"{\n \"gitignore\": true,\n \"config\": {\n \"default\": true,\n \"MD013\": false\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"Markdownlint Rules Reference","type":"text","marks":[{"type":"link","attrs":{"href":"references/markdownlint-rules.md","title":null}}]},{"text":" for all rules.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 2: Add to package.json","type":"text"}]},{"type":"paragraph","content":[{"text":"If you don't have a ","type":"text"},{"text":"package.json","type":"text","marks":[{"type":"code_inline"}]},{"text":", create one:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"name\": \"your-repo-name\",\n \"private\": true,\n \"scripts\": {\n \"lint:md\": \"markdownlint-cli2 \\\"**/*.md\\\"\",\n \"lint:md:fix\": \"markdownlint-cli2 \\\"**/*.md\\\" --fix\"\n },\n \"devDependencies\": {\n \"markdownlint-cli2\": \"^0.20.0\"\n },\n \"engines\": {\n \"node\": \">=20.0.0\"\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Then install:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"npm install","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 3: Add to .gitignore","type":"text"}]},{"type":"paragraph","content":[{"text":"Ensure ","type":"text"},{"text":"node_modules/","type":"text","marks":[{"type":"code_inline"}]},{"text":" is in your ","type":"text"},{"text":".gitignore","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"gitignore"},"content":[{"text":"node_modules/","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 4: Add CI Workflow (Optional)","type":"text"}]},{"type":"paragraph","content":[{"text":"Create ","type":"text"},{"text":".github/workflows/markdown-lint.yml","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"name: Markdown Lint\n\non:\n pull_request:\n paths: ['**.md']\n push:\n branches: [main]\n paths: ['**.md']\n\njobs:\n lint:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v5\n - uses: DavidAnson/markdownlint-cli2-action@v22\n with:\n globs: '**/*.md'","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 5: Run Linting","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"npm run lint:md # Check\nnpm run lint:md:fix # Auto-fix","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Verification Checklist","type":"text"}]},{"type":"checkbox_list","attrs":{"id":null},"content":[{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":".markdownlint-cli2.jsonc","type":"text","marks":[{"type":"code_inline"}]},{"text":" exists with your rules","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"package.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" has lint:md scripts","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"node_modules/","type":"text","marks":[{"type":"code_inline"}]},{"text":" is in ","type":"text"},{"text":".gitignore","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"npm run lint:md","type":"text","marks":[{"type":"code_inline"}]},{"text":" works locally","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"CI workflow runs on PRs (if added)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quick Start","type":"text"}]},{"type":"paragraph","content":[{"text":"Option 1: Using npx (zero setup required):","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Check all markdown files\nnpx markdownlint-cli2 \"**/*.md\"\n\n# Auto-fix issues\nnpx markdownlint-cli2 \"**/*.md\" --fix","type":"text"}]},{"type":"paragraph","content":[{"text":"Option 2: Using npm scripts (if configured):","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Check all markdown files for linting errors\nnpm run lint:md\n\n# Auto-fix fixable linting issues\nnpm run lint:md:fix","type":"text"}]},{"type":"paragraph","content":[{"text":"Option 3: VS Code extension for real-time linting (optional/advanced):","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Install ","type":"text"},{"text":"davidanson.vscode-markdownlint","type":"text","marks":[{"type":"code_inline"}]},{"text":" from VS Code marketplace","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create ","type":"text"},{"text":".markdownlint-cli2.jsonc","type":"text","marks":[{"type":"code_inline"}]},{"text":" configuration (see installation guide)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Linting happens as you type with auto-fix on save enabled (if configured)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Unified Tooling Architecture","type":"text"}]},{"type":"paragraph","content":[{"text":"When configured, ","type":"text"},{"text":"markdownlint-cli2","type":"text","marks":[{"type":"code_inline"}]},{"text":" can be used everywhere to ensure zero configuration drift:","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Tooling Components","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CLI Tool","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"markdownlint-cli2","type":"text","marks":[{"type":"code_inline"}]},{"text":") - ","type":"text"},{"text":"Core component, use this first","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Can be run via npx (zero setup) or local install","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Used for local validation and pre-commit checks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Foundation for all other integrations","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"VS Code Extension","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"davidanson.vscode-markdownlint","type":"text","marks":[{"type":"code_inline"}]},{"text":") - ","type":"text"},{"text":"Optional/Advanced","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Uses same ","type":"text"},{"text":"markdownlint-cli2","type":"text","marks":[{"type":"code_inline"}]},{"text":" engine as CLI","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Real-time linting as you type","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auto-fix on save and paste (configurable in ","type":"text"},{"text":".vscode/settings.json","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"VS Code Extension Setup","type":"text","marks":[{"type":"link","attrs":{"href":"references/vscode-extension-setup.md","title":null}}]}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitHub Actions","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"markdownlint-cli2-action","type":"text","marks":[{"type":"code_inline"}]},{"text":") - ","type":"text"},{"text":"Optional/Advanced","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Same engine as VS Code and CLI","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Runs automatically on PRs that modify markdown files (when configured)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Same rules as local development (no surprises)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"GitHub Actions Configuration","type":"text","marks":[{"type":"link","attrs":{"href":"references/github-actions-config.md","title":null}}]}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Configuration Source","type":"text"}]},{"type":"paragraph","content":[{"text":"All tools read ","type":"text"},{"text":".markdownlint-cli2.jsonc","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the project root as the single source of truth:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"jsonc"},"content":[{"text":"{\n \"gitignore\": true,\n \"ignores\": [\"vendor/**/*.md\"],\n \"config\": {\n \"default\": true,\n \"MD013\": false\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"What this contains:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"gitignore","type":"text","marks":[{"type":"code_inline"}]},{"text":": Automatically excludes files from ","type":"text"},{"text":".gitignore","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ignores","type":"text","marks":[{"type":"code_inline"}]},{"text":": Additional glob patterns to exclude from linting","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"config","type":"text","marks":[{"type":"code_inline"}]},{"text":": Linting rules (all defaults enabled, MD013 disabled for long lines)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Configuration precedence","type":"text","marks":[{"type":"strong"}]},{"text":" (in decreasing order):","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":".markdownlint-cli2.{jsonc,yaml,cjs}","type":"text","marks":[{"type":"code_inline"}]},{"text":" file - ","type":"text"},{"text":"Single source of truth","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"VS Code user/workspace settings (avoid - not portable)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Default configuration","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Note:","type":"text","marks":[{"type":"strong"}]},{"text":" Changes to ","type":"text"},{"text":".markdownlint-cli2.jsonc","type":"text","marks":[{"type":"code_inline"}]},{"text":" apply instantly to all tools (VS Code, CLI, GitHub Actions)","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"CRITICAL: Configuration Policy","type":"text"}]},{"type":"paragraph","content":[{"text":"IMPORTANT - Read this before modifying any configuration:","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Strict Policy - Never Modify Without Approval","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"DO NOT modify ","type":"text","marks":[{"type":"strong"}]},{"text":".markdownlint-cli2.jsonc","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" without explicit approval","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Strict linting rules are intentional and enforce documentation quality","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If linting errors occur, ","type":"text"},{"text":"fix the content to comply with the rules","type":"text","marks":[{"type":"strong"}]},{"text":", NOT the rules themselves","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Only request rule changes if there is a ","type":"text"},{"text":"compelling architectural reason","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When in doubt, ","type":"text"},{"text":"ask before relaxing any linting rules","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Why This Policy Exists","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Quality enforcement","type":"text","marks":[{"type":"strong"}]},{"text":": Linting rules maintain documentation consistency and professionalism","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Best practices","type":"text","marks":[{"type":"strong"}]},{"text":": Rules encode markdown best practices accumulated over years","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Accessibility","type":"text","marks":[{"type":"strong"}]},{"text":": Many rules improve screen reader and markdown parser compatibility","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Maintainability","type":"text","marks":[{"type":"strong"}]},{"text":": Consistent formatting makes documentation easier to maintain","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Collaboration","type":"text","marks":[{"type":"strong"}]},{"text":": Shared standards reduce friction in code reviews","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Proper Response to Linting Errors","type":"text"}]},{"type":"paragraph","content":[{"text":"Correct approach:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"Error: MD022/blanks-around-headings - Headings should be surrounded by blank lines\n\nAction: Add blank lines before and after the heading in the markdown file","type":"text"}]},{"type":"paragraph","content":[{"text":"Incorrect approach:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"Error: MD022/blanks-around-headings - Headings should be surrounded by blank lines\n\nAction: Disable MD022 rule in .markdownlint-cli2.jsonc","type":"text"}]},{"type":"paragraph","content":[{"text":"Exception:","type":"text","marks":[{"type":"strong"}]},{"text":" If you genuinely believe a rule should be modified, present your case to the user with:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The specific rule and why it's problematic","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Examples of where it causes issues","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Architectural or usability rationale","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Proposed configuration change","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The user will make the final decision on whether to modify the configuration.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"CRITICAL: NO AUTOMATED SCRIPTS","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"⚠️ SCRIPTS ARE STRICTLY PROHIBITED FOR MARKDOWN LINTING FIXES ⚠️","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"paragraph","content":[{"text":"NEVER use automated scripts to fix markdown files.","type":"text","marks":[{"type":"strong"}]},{"text":" This includes:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Python/Bash scripts that modify multiple files at once","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Regex-based find-and-replace operations across files","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Any automated tool that makes bulk changes without human review per-change","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Smart\" fixers that detect and add language specifiers to code blocks","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Why This Policy Exists","type":"text"}]},{"type":"paragraph","content":[{"text":"A) Scripts are dangerous - we have seen real issues:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Context blindness","type":"text","marks":[{"type":"strong"}]},{"text":": Scripts cannot understand semantic context (e.g., a code block showing tool output vs actual code that needs syntax highlighting)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Over-application","type":"text","marks":[{"type":"strong"}]},{"text":": Scripts apply fixes uniformly, even where inappropriate","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cascading damage","type":"text","marks":[{"type":"strong"}]},{"text":": One wrong assumption affects hundreds of files, requiring painful manual cleanup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"False language detection","type":"text","marks":[{"type":"strong"}]},{"text":": Adding ","type":"text"},{"text":"text","type":"text","marks":[{"type":"code_inline"}]},{"text":" or other language specifiers to blocks that intentionally have none","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"B) Manual fixes are slower but more accurate and safer:","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"While manually fixing linting errors one-by-one takes longer, it ensures:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Each change is reviewed in context before application","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Semantic meaning is preserved (not just syntactic correctness)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Edge cases are handled appropriately","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No collateral damage to unrelated content","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The speed/accuracy trade-off is worth it.","type":"text","marks":[{"type":"strong"}]},{"text":" A script that \"saves time\" but requires hours of cleanup is a net loss.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Nested Code Blocks: A Critical Complexity","type":"text"}]},{"type":"paragraph","content":[{"text":"Documentation often contains ","type":"text"},{"text":"markdown within markdown","type":"text","marks":[{"type":"strong"}]},{"text":" - examples showing how to write markdown, skill documentation with code samples, templates, etc. This creates nested structures that scripts cannot handle correctly:","type":"text"}]},{"type":"paragraph","content":[{"text":"Example: A skill showing how to write a code block:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"Here's how to create a Python code block:\n\n````markdown\n```python\ndef hello():\n print(\"Hello, world!\")\n```\n````","type":"text"}]},{"type":"paragraph","content":[{"text":"In this example:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The outer fence uses 4 backticks (`````markdown`)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The inner fence uses 3 backticks (","type":"text"},{"text":"```python","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A script seeing ","type":"text"},{"text":"```","type":"text","marks":[{"type":"code_inline"}]},{"text":" might incorrectly add language specifiers or break the nesting","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Common nested patterns to watch for:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"```{language}","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Regular code block with syntax highlighting","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"````markdown","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Wrapper showing markdown examples (uses 4+ backticks)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Code blocks inside code blocks (documentation about documentation)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Example output that should NOT have language specifiers","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Scripts cannot reliably distinguish:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Which backtick fence is the \"real\" one vs an example","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Whether a bare ","type":"text"},{"text":"```","type":"text","marks":[{"type":"code_inline"}]},{"text":" is intentional (raw output) or needs a language","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The semantic purpose of each code block","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Real-World Failure Example","type":"text"}]},{"type":"paragraph","content":[{"text":"A script added ","type":"text"},{"text":"text","type":"text","marks":[{"type":"code_inline"}]},{"text":" language specifiers to code blocks showing MCP tool output, Notion searches, and other non-code examples. These blocks were intentionally bare (no language specifier) to show raw output without syntax highlighting. The script's \"fix\" required hundreds of manual edits to undo.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"The ONLY Acceptable Approach","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run ","type":"text"},{"text":"markdownlint-cli2 --fix","type":"text","marks":[{"type":"code_inline"}]},{"text":" for safe, built-in auto-fixes (trailing spaces, blank lines, etc.)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For \"unfixable\" errors (MD040, MD024, etc.), use the ","type":"text"},{"text":"Edit tool","type":"text","marks":[{"type":"strong"}]},{"text":" to make targeted, contextual fixes one at a time","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Review each change before applying","type":"text","marks":[{"type":"strong"}]},{"text":" - understand WHY the error exists and whether the fix is semantically correct","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Look at surrounding context","type":"text","marks":[{"type":"strong"}]},{"text":" - is this a nested code block? An example? Raw output?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If a fix seems mechanical/repetitive, ","type":"text"},{"text":"STOP and ask the user","type":"text","marks":[{"type":"strong"}]},{"text":" before proceeding","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"If You Even Consider Using a Script","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"STOP immediately","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ask the user explicitly","type":"text","marks":[{"type":"strong"}]},{"text":": \"I'm considering automating this with a script. Are you sure? Scripts have caused painful cleanup in the past.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Only proceed if user explicitly confirms","type":"text","marks":[{"type":"strong"}]},{"text":" AND you've triple-checked the script logic","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Test on ONE file first","type":"text","marks":[{"type":"strong"}]},{"text":" and show the user the diff before bulk application","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"MD040 (fenced-code-language) Special Guidance","type":"text"}]},{"type":"paragraph","content":[{"text":"The MD040 rule requires code blocks to have language specifiers. However:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"DO NOT","type":"text","marks":[{"type":"strong"}]},{"text":" blindly add ","type":"text"},{"text":"text","type":"text","marks":[{"type":"code_inline"}]},{"text":" to all blocks without language specifiers","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Some blocks intentionally have no language (showing raw output, examples, templates)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ask yourself: \"Is this showing code that needs syntax highlighting, or raw output?\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When in doubt, ","type":"text"},{"text":"ask the user","type":"text","marks":[{"type":"strong"}]},{"text":" rather than guessing","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Questions to ask before adding a language specifier:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Is this actual code, or example output/results?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Is this inside a larger markdown example (nested)?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Would syntax highlighting help or hurt readability here?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Did the author intentionally leave it bare?","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Running Linting Locally","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"CRITICAL: Auto-Fix Workflow","type":"text"}]},{"type":"paragraph","content":[{"text":"When running linting validation, ALWAYS automatically fix ALL errors (both fixable and \"unfixable\") without asking for user confirmation.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Workflow:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run linting validation command (npx or npm scripts)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If errors are found:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"IMMEDIATELY run the auto-fix command","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"--fix","type":"text","marks":[{"type":"code_inline"}]},{"text":" flag) without prompting","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Report what was auto-fixed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For any remaining \"unfixable\" errors:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read the affected files to understand context","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Analyze the error and surrounding content","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Apply intelligent fixes based on context (see \"Intelligent Fix Handling\" below)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Re-run linting to verify fixes","type":"text"}]}]}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If no errors are found, report success","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"DO NOT ask \"Would you like me to auto-fix?\" or \"Would you like me to investigate?\" - just fix everything automatically.","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Prerequisites","type":"text"}]},{"type":"paragraph","content":[{"text":"For npx approach (zero setup):","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Node.js 18+ and npm 8+ installed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No additional setup required","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For local install approach:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Install dependencies (first time only)\nnpm install","type":"text"}]},{"type":"paragraph","content":[{"text":"If your project doesn't have ","type":"text"},{"text":"markdownlint-cli2","type":"text","marks":[{"type":"code_inline"}]},{"text":" installed, see the ","type":"text"},{"text":"Installation and Setup Guide","type":"text","marks":[{"type":"link","attrs":{"href":"references/installation-setup.md","title":null}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Check All Markdown Files","type":"text"}]},{"type":"paragraph","content":[{"text":"With npx:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"npx markdownlint-cli2 \"**/*.md\"","type":"text"}]},{"type":"paragraph","content":[{"text":"With npm scripts (if configured):","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"npm run lint:md","type":"text"}]},{"type":"paragraph","content":[{"text":"What this does:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Runs ","type":"text"},{"text":"markdownlint-cli2","type":"text","marks":[{"type":"code_inline"}]},{"text":" against all ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":" files in the project","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Automatically excludes ","type":"text"},{"text":"node_modules","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Outputs errors with file paths and line numbers","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Exit code 0 if no errors, non-zero if errors found","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example output:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"text"},"content":[{"text":"docs/setup-guide.md:45:1 MD022/blanks-around-headings Headings should be surrounded by blank lines\nREADME.md:12:81 MD009/no-trailing-spaces Trailing spaces","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Auto-Fix Fixable Issues","type":"text"}]},{"type":"paragraph","content":[{"text":"With npx:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"npx markdownlint-cli2 \"**/*.md\" --fix","type":"text"}]},{"type":"paragraph","content":[{"text":"With npm scripts (if configured):","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"npm run lint:md:fix","type":"text"}]},{"type":"paragraph","content":[{"text":"What this does:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Automatically fixes issues that can be safely corrected","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Modifies files in place","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reports remaining unfixable issues","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Fixable issues include:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Trailing spaces (MD009)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Missing blank lines (MD012, MD022)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"List marker consistency (MD004, MD007)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Code fence style (MD048)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Non-fixable issues require intelligent analysis and manual fixes:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Heading structure (MD001, MD025)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Duplicate headings (MD024)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Line length (MD013, if enabled)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Link references (MD051, MD052)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Intelligent Fix Handling","type":"text"}]},{"type":"paragraph","content":[{"text":"When \"unfixable\" errors remain after auto-fix, automatically analyze and fix them.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"For detailed strategies on handling each error type, see the dedicated guide:","type":"text"}]},{"type":"paragraph","content":[{"text":"Intelligent Fixing Guide","type":"text","marks":[{"type":"link","attrs":{"href":"references/intelligent-fixing-guide.md","title":null}},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"This guide covers:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MD024 - Duplicate Headings (context-aware renaming or removal)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MD001/MD025 - Heading Structure (hierarchy fixes)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MD051/MD052 - Link References (anchor and reference link corrections)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MD013 - Line Length (intelligent wrapping)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"General principles for context-aware analysis","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verification and reporting best practices","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Performance optimization with parallel Task agents","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Quick summary:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run auto-fix first: ","type":"text"},{"text":"npx markdownlint-cli2 \"**/*.md\" --fix","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For remaining errors, read affected files to understand context","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Apply intelligent fixes based on error patterns (see guide)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Always re-run linting to verify all errors are resolved","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Report what was fixed and how","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"VS Code Extension Setup (Optional/Advanced)","type":"text"}]},{"type":"paragraph","content":[{"text":"For VS Code integration","type":"text","marks":[{"type":"strong"}]},{"text":", see the dedicated guide:","type":"text"}]},{"type":"paragraph","content":[{"text":"VS Code Extension Setup Guide","type":"text","marks":[{"type":"link","attrs":{"href":"references/vscode-extension-setup.md","title":null}},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The VS Code extension (","type":"text"},{"text":"davidanson.vscode-markdownlint","type":"text","marks":[{"type":"code_inline"}]},{"text":") provides real-time linting in your editor. The guide covers:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Extension installation and verification","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auto-fix configuration (format on save, format on paste)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Interactive linting features (squiggly underlines, quick fixes)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keyboard shortcuts for all fix methods","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Configuration precedence and troubleshooting","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Best practices for team usage","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"This is optional but highly recommended for regular markdown work.","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"GitHub Actions Integration (Optional/Advanced)","type":"text"}]},{"type":"paragraph","content":[{"text":"For CI/CD integration","type":"text","marks":[{"type":"strong"}]},{"text":", see the dedicated guide:","type":"text"}]},{"type":"paragraph","content":[{"text":"GitHub Actions Configuration Guide","type":"text","marks":[{"type":"link","attrs":{"href":"references/github-actions-config.md","title":null}},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"GitHub Actions can automatically validate markdown files on PRs and pushes. The guide covers:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Complete workflow file configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Trigger setup (PR and push events with path filtering)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Action versions (checkout@v5, markdownlint-cli2-action@v22)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Workflow execution flow and results interpretation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Viewing and fixing CI failures","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Advanced configuration (custom globs, auto-fix, branch protection)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Troubleshooting common issues","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"This is optional but highly recommended for team projects.","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Customizing Rules (Requires Approval)","type":"text"}]},{"type":"paragraph","content":[{"text":"WARNING: Only modify with explicit approval per policy above.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"For detailed rule information","type":"text","marks":[{"type":"strong"}]},{"text":", see the comprehensive guide:","type":"text"}]},{"type":"paragraph","content":[{"text":"Markdownlint Rules Reference","type":"text","marks":[{"type":"link","attrs":{"href":"references/markdownlint-rules.md","title":null}},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The rules reference covers:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"All 60+ MD rules with descriptions and examples","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Rule categories (auto-fixable vs manual-fix required)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Configuration syntax for customizing rules","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Common rule modifications (disable, configure parameters)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Inline comment syntax for per-file overrides","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Links to official documentation for each rule","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Quick syntax reminder:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"default\": true, // Enable all defaults\n \"MD013\": false, // Disable specific rule\n \"MD033\": { // Configure with options\n \"allowed_elements\": [\"br\"]\n }\n}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Troubleshooting","type":"text"}]},{"type":"paragraph","content":[{"text":"Common issues and solutions:","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Issue: \"Command not found: markdownlint-cli2\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Solution:","type":"text","marks":[{"type":"strong"}]},{"text":" Run ","type":"text"},{"text":"npm install","type":"text","marks":[{"type":"code_inline"}]},{"text":" or use npx: ","type":"text"},{"text":"npx markdownlint-cli2 \"**/*.md\"","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Issue: Too many linting errors to fix manually","type":"text"}]},{"type":"paragraph","content":[{"text":"Solution:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run auto-fix: ","type":"text"},{"text":"npx markdownlint-cli2 \"**/*.md\" --fix","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Fix remaining errors in batches","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"Installation Guide","type":"text","marks":[{"type":"link","attrs":{"href":"references/installation-setup.md","title":null}}]},{"text":" for detailed troubleshooting","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Issue: VS Code or GitHub Actions problems","type":"text"}]},{"type":"paragraph","content":[{"text":"For detailed troubleshooting","type":"text","marks":[{"type":"strong"}]},{"text":", see the dedicated guides:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"VS Code issues","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"VS Code Extension Setup","type":"text","marks":[{"type":"link","attrs":{"href":"references/vscode-extension-setup.md#troubleshooting","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitHub Actions issues","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"GitHub Actions Configuration","type":"text","marks":[{"type":"link","attrs":{"href":"references/github-actions-config.md#troubleshooting","title":null}}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Issue: Unclear rule violations","type":"text"}]},{"type":"paragraph","content":[{"text":"Solution:","type":"text","marks":[{"type":"strong"}]},{"text":" Check ","type":"text"},{"text":"Markdownlint Rules Reference","type":"text","marks":[{"type":"link","attrs":{"href":"references/markdownlint-rules.md","title":null}}]},{"text":" for rule explanations, examples, and official documentation links.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Best Practices","type":"text"}]},{"type":"paragraph","content":[{"text":"For comprehensive best practices on markdown linting, configuration management, collaboration, and skill automation:","type":"text"}]},{"type":"paragraph","content":[{"text":"Best Practices Guide","type":"text","marks":[{"type":"link","attrs":{"href":"references/best-practices.md","title":null}},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The guide covers:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Writing markdown effectively with linting in mind","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Configuration management and rule customization","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Collaboration patterns and team workflows","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Skill automation for Claude Code usage","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When and how to use parallel Task agents for efficiency","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Resources","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Official Documentation","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"markdownlint-cli2 README:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"github.com/DavidAnson/markdownlint-cli2","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/DavidAnson/markdownlint-cli2","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"markdownlint rules:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"VS Code extension:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint","type":"text","marks":[{"type":"link","attrs":{"href":"https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitHub Action:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"github.com/DavidAnson/markdownlint-cli2-action","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/DavidAnson/markdownlint-cli2-action","title":null}}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Project Configuration Files","type":"text"}]},{"type":"paragraph","content":[{"text":"These files should be created in your project root (see installation guides for setup):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Configuration:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":".markdownlint-cli2.jsonc","type":"text","marks":[{"type":"code_inline"}]},{"text":" (required for custom rules)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"NPM scripts:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"package.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" (optional, for npm run commands)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"VS Code settings:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":".vscode/settings.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" (optional, for auto-fix on save)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitHub workflow:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":".github/workflows/markdown-lint.yml","type":"text","marks":[{"type":"code_inline"}]},{"text":" (optional, for CI/CD)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Supporting Documentation","type":"text"}]},{"type":"paragraph","content":[{"text":"This skill includes reference documentation in the ","type":"text"},{"text":"references/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/installation-setup.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/installation-setup.md","title":null}}]},{"text":" - ","type":"text"},{"text":"Start here:","type":"text","marks":[{"type":"strong"}]},{"text":" Installation and first-time setup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/intelligent-fixing-guide.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/intelligent-fixing-guide.md","title":null}}]},{"text":" - Strategies for fixing \"unfixable\" errors","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/markdownlint-rules.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/markdownlint-rules.md","title":null}}]},{"text":" - Detailed rule explanations and customization","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/best-practices.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/best-practices.md","title":null}}]},{"text":" - Best practices for writing, configuration, collaboration, and automation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/vscode-extension-setup.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/vscode-extension-setup.md","title":null}}]},{"text":" - VS Code integration guide (optional/advanced)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/github-actions-config.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/github-actions-config.md","title":null}}]},{"text":" - CI/CD workflow setup (optional/advanced)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Evaluation Scenarios","type":"text"}]},{"type":"paragraph","content":[{"text":"These scenarios are used to evaluate skill activation, guidance quality, and multi-model compatibility.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Scenario 1: First-time setup","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"name\": \"First-time setup\",\n \"query\": \"I need to set up markdown linting in my project\",\n \"context\": \"User has no existing markdown linting configuration\",\n \"files\": [],\n \"expected_behavior\": [\n \"Skill activates successfully\",\n \"Loads references/installation-setup.md for comprehensive guidance\",\n \"Provides step-by-step installation instructions\",\n \"Distinguishes between npx (zero-setup) and local install approaches\",\n \"Guides through .markdownlint-cli2.jsonc configuration\",\n \"Includes verification steps\"\n ],\n \"test_models\": [\"sonnet\", \"haiku\", \"opus\"]\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Scenario 2: Fix linting errors","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"name\": \"Fix linting errors\",\n \"query\": \"I'm getting MD022 errors, how do I fix them?\",\n \"context\": \"User has linting errors and needs guidance on fixes\",\n \"files\": [\"sample-file.md\"],\n \"expected_behavior\": [\n \"Skill activates for error type and rule explanation\",\n \"Explains MD022 rule (blanks around headings)\",\n \"Provides auto-fix command (npx markdownlint-cli2 --fix)\",\n \"Explains both automatic and intelligent fix approaches\",\n \"References intelligent-fixing-guide.md if needed\",\n \"Provides verification steps\"\n ],\n \"test_models\": [\"sonnet\", \"haiku\", \"opus\"]\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Scenario 3: VS Code integration","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"name\": \"VS Code integration\",\n \"query\": \"How do I enable auto-fix on save in VS Code?\",\n \"context\": \"User wants to integrate markdown linting into their editor workflow\",\n \"files\": [],\n \"expected_behavior\": [\n \"Skill activates for VS Code integration\",\n \"Loads references/vscode-extension-setup.md\",\n \"Provides extension installation instructions\",\n \"Explains auto-fix configuration in .vscode/settings.json\",\n \"Documents keyboard shortcuts and interactive features\",\n \"Includes troubleshooting for common VS Code issues\"\n ],\n \"test_models\": [\"sonnet\", \"haiku\", \"opus\"]\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Scenario 4: GitHub Actions CI setup","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"name\": \"GitHub Actions CI setup\",\n \"query\": \"Add markdown linting to GitHub Actions\",\n \"context\": \"User wants to automate markdown validation in CI/CD pipeline\",\n \"files\": [\".github/workflows/\"],\n \"expected_behavior\": [\n \"Skill activates for GitHub Actions integration\",\n \"Loads references/github-actions-config.md\",\n \"Provides complete workflow file configuration\",\n \"Explains trigger setup (PR and push events)\",\n \"Documents workflow execution and results interpretation\",\n \"Includes configuration for auto-fix and branch protection\"\n ],\n \"test_models\": [\"sonnet\", \"haiku\", \"opus\"]\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Scenario 5: Configuration customization","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"name\": \"Configuration customization\",\n \"query\": \"How do I disable MD013 line length rule?\",\n \"context\": \"User needs to customize linting rules for their project\",\n \"files\": [\".markdownlint-cli2.jsonc\"],\n \"expected_behavior\": [\n \"Skill activates for rule customization\",\n \"Explains configuration policy (fix content, not rules)\",\n \"Provides .markdownlint-cli2.jsonc configuration example\",\n \"Shows syntax for disabling/configuring specific rules\",\n \"References references/markdownlint-rules.md for rule details\",\n \"Emphasizes verification of changes across all tools\"\n ],\n \"test_models\": [\"sonnet\", \"haiku\", \"opus\"]\n}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Multi-Model Testing Notes","type":"text"}]},{"type":"paragraph","content":[{"text":"Tested with","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Claude Sonnet","type":"text","marks":[{"type":"strong"}]},{"text":": Optimal performance, follows hub architecture well","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Claude Haiku","type":"text","marks":[{"type":"strong"}]},{"text":": (To be tested - should work given explicit instructions)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Claude Opus","type":"text","marks":[{"type":"strong"}]},{"text":": (To be tested - may over-analyze, content is appropriately scoped)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Observations","type":"text","marks":[{"type":"strong"}]},{"text":": Skill's explicit command examples and clear decision trees should work well across all model tiers.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Version History","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"v2.0.0 (2025-11-30): Migrated to code-quality plugin in claude-code-plugins repo","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"v1.2.0 (2025-11-17): Extracted Intelligent Fixing Guide - moved detailed error fixing strategies to separate reference file, reduced SKILL.md size for better token efficiency","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"v1.1.0 (2025-11-17): Deduplicated content - removed duplicated reference material, streamlined to hub architecture","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"v1.0.2 (2025-11-17): Version updates - updated to markdownlint-cli2 v0.19.0, Node 20+ requirement, action v21","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"v1.0.1 (2025-01-09): Improved portability - removed repository-specific language, enhanced first-use guidance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"v1.0.0 (2025-01-09): Initial release - migrated from ","type":"text"},{"text":".claude/memory/workflows.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Last Updated","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Date:","type":"text","marks":[{"type":"strong"}]},{"text":" 2026-01-17 ","type":"text"},{"text":"Model:","type":"text","marks":[{"type":"strong"}]},{"text":" claude-opus-4-5-20251101","type":"text"}]}]},"metadata":{"date":"2026-06-05","name":"markdown-linting","author":"@skillopedia","source":{"stars":76,"repo_name":"claude-code-plugins","origin_url":"https://github.com/melodic-software/claude-code-plugins/blob/HEAD/plugins/code-quality/skills/markdown-linting/SKILL.md","repo_owner":"melodic-software","body_sha256":"2556ab0b51b84745619c89d4b89a50d19b9f1daceb923be80e1383f270aabfd0","cluster_key":"73823372c9c3091e6d6d12d412bd2cbdb24eb0170c396f3f4da58a7a87f53c9d","clean_bundle":{"format":"clean-skill-bundle-v1","source":"melodic-software/claude-code-plugins/plugins/code-quality/skills/markdown-linting/SKILL.md","attachments":[{"id":"2eacc530-d743-54e4-8e36-0648eb8eb63d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/2eacc530-d743-54e4-8e36-0648eb8eb63d/attachment.md","path":"references/best-practices.md","size":3293,"sha256":"fad42d572dae7150cf1b6e78e80276e40b7568eb7314c1fb8c91274f2146c32f","contentType":"text/markdown; charset=utf-8"},{"id":"3994d2b9-466f-5c0c-939f-57cc3c91372d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/3994d2b9-466f-5c0c-939f-57cc3c91372d/attachment.md","path":"references/flavors/commonmark.md","size":4329,"sha256":"bf9dce08e1ee8011a432612852c9a2c9dad4a84ec4d13ca703fbf39c100891f4","contentType":"text/markdown; charset=utf-8"},{"id":"7d092da5-ea34-51f4-a2fd-cbf0cf8cafda","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7d092da5-ea34-51f4-a2fd-cbf0cf8cafda/attachment.md","path":"references/flavors/gfm.md","size":6253,"sha256":"b7bc8844c88ce616e66bba56e8b6abbaf8cbaf07284ca4fd5e5e1f412c41d508","contentType":"text/markdown; charset=utf-8"},{"id":"b32a76f9-3375-5e55-86d7-a4026d8d8451","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b32a76f9-3375-5e55-86d7-a4026d8d8451/attachment.md","path":"references/flavors/overview.md","size":5856,"sha256":"d299bce34aefd89c84b839610f4102269b6a61d28be70f718e8c780b8a354a88","contentType":"text/markdown; charset=utf-8"},{"id":"3ed5db85-4343-5921-96ad-de8b6213a546","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/3ed5db85-4343-5921-96ad-de8b6213a546/attachment.md","path":"references/github-actions-config.md","size":13455,"sha256":"feb5df868ea03fba9f2f4beb80dd28b63de6f2efca3f390a40ddd784789350fe","contentType":"text/markdown; charset=utf-8"},{"id":"d20859b6-9dc0-5107-8557-122308709303","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d20859b6-9dc0-5107-8557-122308709303/attachment.md","path":"references/installation-setup.md","size":20905,"sha256":"80f08d73f8312635c348a512df2006ead551300a2fbb02f5f2a722fbbc70418e","contentType":"text/markdown; charset=utf-8"},{"id":"14a08f2e-16b6-59c3-86b3-8562ed8d4b4c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/14a08f2e-16b6-59c3-86b3-8562ed8d4b4c/attachment.md","path":"references/intelligent-fixing-guide.md","size":5909,"sha256":"d8509970efaa71dbb9ca7de2e3ce46e52b5f2fa06010eb50966cc67189e7622b","contentType":"text/markdown; charset=utf-8"},{"id":"34eaa93a-d454-5a24-99f0-2c4574ab0dd5","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/34eaa93a-d454-5a24-99f0-2c4574ab0dd5/attachment.md","path":"references/markdownlint-rules.md","size":11601,"sha256":"b8962edbd7294d412a29e1bc3283672f64d2cdf51cd313fe9108f518ae49a699","contentType":"text/markdown; charset=utf-8"},{"id":"c504fe91-07d9-509d-9032-6c3e515bbfdc","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/c504fe91-07d9-509d-9032-6c3e515bbfdc/attachment.md","path":"references/vscode-extension-setup.md","size":12752,"sha256":"203d536fd5dd47b1d6462baefdd27b34124b301522f97d2faacc4b1aeeb7f0c3","contentType":"text/markdown; charset=utf-8"},{"id":"1784c768-a670-5f39-951a-c71ab189ebf4","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1784c768-a670-5f39-951a-c71ab189ebf4/attachment.md","path":"scripts/README.md","size":7242,"sha256":"0dd011b66e75fea691592de483c9788eb4a4025c77010bda90ac39ca5d6f87c6","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"5c7c24ee96f97aef5248e62d1d264f7a4fe0a752ddcfcefaf40ec3ace7fafc39","attachment_count":10,"text_attachments":10,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"plugins/code-quality/skills/markdown-linting/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"devops-infrastructure","category_label":"DevOps"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"devops-infrastructure","import_tag":"clean-skills-v1","description":"Comprehensive markdown linting guidance using markdownlint-cli2. Run, execute, check, and validate markdown files. Fix linting errors (MD0XX rules). Configure .markdownlint-cli2.jsonc (rules and ignores). Set up VS Code extension and GitHub Actions workflows. Supports markdown flavors including GitHub Flavored Markdown (GFM) and CommonMark. Use when working with markdown files, encountering validation errors, configuring markdownlint, setting up linting workflows, troubleshooting linting issues, establishing markdown quality standards, or configuring flavor-specific rules for tables, task lists, and strikethrough.","allowed-tools":"Read, Bash, Glob, Grep"}},"renderedAt":1782980018197}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.