{"id":34248138,"url":"https://github.com/joshrotenberg/mdbook-lint","last_synced_at":"2026-03-04T03:03:07.369Z","repository":{"id":308074083,"uuid":"1031554166","full_name":"joshrotenberg/mdbook-lint","owner":"joshrotenberg","description":"An mdbook linting tool","archived":false,"fork":false,"pushed_at":"2026-02-01T22:24:39.000Z","size":5682,"stargazers_count":22,"open_issues_count":12,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-01T23:48:09.350Z","etag":null,"topics":["lint","linter","markdown","mdbook","mdbook-plugins","mdbook-preprocessor"],"latest_commit_sha":null,"homepage":"https://joshrotenberg.com/mdbook-lint/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joshrotenberg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-04T01:27:18.000Z","updated_at":"2026-02-01T22:24:42.000Z","dependencies_parsed_at":"2025-08-31T19:16:24.356Z","dependency_job_id":"4ff82e2d-88d3-477d-bfac-65e84f041dbe","html_url":"https://github.com/joshrotenberg/mdbook-lint","commit_stats":null,"previous_names":["joshrotenberg/mdbook-lint"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/joshrotenberg/mdbook-lint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshrotenberg%2Fmdbook-lint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshrotenberg%2Fmdbook-lint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshrotenberg%2Fmdbook-lint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshrotenberg%2Fmdbook-lint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshrotenberg","download_url":"https://codeload.github.com/joshrotenberg/mdbook-lint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshrotenberg%2Fmdbook-lint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30064802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T18:21:05.932Z","status":"ssl_error","status_checked_at":"2026-03-03T18:20:59.341Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lint","linter","markdown","mdbook","mdbook-plugins","mdbook-preprocessor"],"created_at":"2025-12-16T08:04:39.671Z","updated_at":"2026-03-04T03:03:07.357Z","avatar_url":"https://github.com/joshrotenberg.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mdbook-lint\n\n[![Crates.io](https://img.shields.io/crates/v/mdbook-lint.svg)](\u003chttps://crates.io/crates/mdbook-lint\u003e)\n[![Documentation](https://docs.rs/mdbook-lint/badge.svg)](\u003chttps://docs.rs/mdbook-lint\u003e)\n[![Build Status](https://github.com/joshrotenberg/mdbook-lint/workflows/CI/badge.svg)](\u003chttps://github.com/joshrotenberg/mdbook-lint/actions\u003e)\n[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](\u003chttps://github.com/joshrotenberg/mdbook-lint#license\u003e)\n\nA fast, configurable linter designed for [mdBook](https://rust-lang.github.io/mdBook/) projects. Works as both an mdBook preprocessor and standalone CLI tool.\n\n**[Documentation](https://joshrotenberg.github.io/mdbook-lint/)** | **[Getting Started](https://joshrotenberg.github.io/mdbook-lint/getting-started.html)**\n\n## What is mdBook?\n\n[mdBook](https://rust-lang.github.io/mdBook/) is a command-line tool for creating books from Markdown files. It's widely used in the Rust ecosystem for documentation, including [The Rust Programming Language](https://doc.rust-lang.org/book/) book, and is popular for technical documentation projects of all kinds. mdBook renders Markdown into a clean, searchable HTML book format with navigation, search, and syntax highlighting.\n\nmdbook-lint helps ensure your mdBook documentation maintains consistent quality by catching common issues before they reach readers.\n\n## Installation\n\n### Homebrew (macOS/Linux)\n\n```bash\nbrew tap joshrotenberg/brew\nbrew install mdbook-lint\n```\n\n### From Cargo\n\n```bash\ncargo install mdbook-lint\n```\n\nBy default, this includes all rule sets (standard, mdBook, and content rules). To install without specific rule sets:\n\n```bash\n# Without content rules (CONTENT001-011)\ncargo install mdbook-lint --no-default-features --features standard,mdbook,lsp\n\n# Only standard markdown rules\ncargo install mdbook-lint --no-default-features --features standard,lsp\n```\n\n### From Prebuilt Binaries\n\nDownload the latest release for your platform from [GitHub Releases](https://github.com/joshrotenberg/mdbook-lint/releases):\n\n- **Linux (x86_64)**: `mdbook-lint-linux-x86_64`\n- **Linux (musl)**: `mdbook-lint-linux-x86_64-musl` (static binary, no dependencies)\n- **Windows**: `mdbook-lint-windows-x86_64.exe`\n- **macOS (Intel)**: `mdbook-lint-macos-x86_64`\n- **macOS (Apple Silicon)**: `mdbook-lint-macos-aarch64`\n\nExtract and add to your PATH, or use with GitHub Actions (see [CI Integration](#ci-integration)).\n\n### Docker\n\n```bash\n# Pull from GitHub Container Registry\ndocker pull ghcr.io/joshrotenberg/mdbook-lint:latest\n\n# Lint files in current directory\ndocker run --rm -v $(pwd):/workspace ghcr.io/joshrotenberg/mdbook-lint lint .\n\n# Show available rules\ndocker run --rm ghcr.io/joshrotenberg/mdbook-lint rules\n\n# Use a specific version\ndocker run --rm -v $(pwd):/workspace ghcr.io/joshrotenberg/mdbook-lint:0.14.2 lint .\n```\n\nAvailable for `linux/amd64` and `linux/arm64`.\n\n### Verify Installation\n\n```bash\nmdbook-lint --version\n```\n\n## Features\n\n- **Native mdBook integration** - Seamless preprocessor integration\n- **100 linting rules** - 55 standard markdown + 18 mdBook-specific + 17 ADR + 10 content rules\n- **Auto-fix support** - Automatically fix common issues with 41 rules\n- **ADR validation** - Validate Architecture Decision Records (Nygard and MADR 4.0)\n- **Fast performance** - Lint entire books in seconds\n- **Configurable** - Disable rules, set custom parameters\n- **Cross-platform** - Prebuilt binaries for all major platforms\n\n## Usage\n\n### mdBook Preprocessor (Primary Use Case)\n\nAdd to your `book.toml`:\n\n```toml\n[preprocessor.lint]\n```\n\nThen run `mdbook build` as usual. The linter will automatically check all your markdown files and report issues during the build process.\n\n### CLI (Standalone)\n\n```bash\n# Lint files\nmdbook-lint lint README.md src/*.md\n\n# Auto-fix violations (using the fix subcommand)\nmdbook-lint fix src/*.md\n\n# Preview what would be fixed\nmdbook-lint fix --dry-run src/*.md\n\n# Alternative: use lint with --fix flag\nmdbook-lint lint --fix src/*.md\n\n# Show available rules\nmdbook-lint rules\n```\n\nOutput uses cargo-style formatting with colors:\n\n```text\nerror[MD001]: Expected heading level 2 but got level 3\n  --\u003e src/chapter.md:15:1\n     |\n  15 | ### Skipped heading level\n     | ^^^ heading-increment\n```\n\n## Configuration\n\nCreate a `.mdbook-lint.toml` file (also supports YAML/JSON):\n\n```toml\n# Disable rules that don't fit your project\ndisabled-rules = [\"MD013\", \"MD033\"]\n\n# Configure specific rules\n[MD007]\nindent = 4\n\n[MD009]\nbr_spaces = 2  # Allow 2 trailing spaces for line breaks\n\n[MD003]\nstyle = \"atx\"  # Use # style headings\n```\n\nGenerate a configuration file with all options documented:\n\n```bash\nmdbook-lint init --include-all\n```\n\n**Configuration examples:**\n\n- [example-mdbook-lint.toml](https://github.com/joshrotenberg/mdbook-lint/blob/main/crates/mdbook-lint-cli/example-mdbook-lint.toml) - Comprehensive reference with all 83 rules documented\n- [docs/.mdbook-lint.toml](https://github.com/joshrotenberg/mdbook-lint/blob/main/docs/.mdbook-lint.toml) - Real-world example used by this project's documentation\n\n## Rules\n\n- **55 standard rules** (MD001-MD060) - All the usual markdown linting\n- **18 mdBook rules** (MDBOOK001-MDBOOK025) - mdBook-specific checks\n- **17 ADR rules** (ADR001-ADR017) - Architecture Decision Record validation (Nygard and MADR 4.0)\n- **10 content rules** (CONTENT001-CONTENT011) - Content quality checks including TODO detection, placeholder text, terminology consistency, link quality, and more\n\nRun `mdbook-lint rules --detailed` to see all available rules.\n\n## CI Integration\n\n### GitHub Actions\n\n```yaml\nname: Lint Documentation\non: [push, pull_request]\n\njobs:\n  lint:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      \n      - name: Download mdbook-lint\n        run: |\n          curl -sSL https://github.com/joshrotenberg/mdbook-lint/releases/latest/download/mdbook-lint-linux-x86_64 -o mdbook-lint\n          chmod +x mdbook-lint\n      \n      - name: Lint markdown files\n        run: ./mdbook-lint lint --fail-on-warnings docs/\n```\n\n## Compatibility\n\nmdbook-lint supports mdBook versions 0.4.x and 0.5.x. The tool automatically detects and handles differences in mdBook's JSON protocol between versions, so it works seamlessly regardless of which mdBook version you have installed.\n\nFor detailed compatibility information, see the [Compatibility Guide](https://joshrotenberg.github.io/mdbook-lint/compatibility.html).\n\n## Contributing\n\nContributions are welcome! See our [Contributing Guide](https://joshrotenberg.github.io/mdbook-lint/contributing.html) for complete information.\n\n## Acknowledgments\n\nmdbook-lint builds on the excellent work of:\n\n- [markdownlint](https://github.com/DavidAnson/markdownlint) - The original Node.js markdown linter that defined the standard rule set (MD001-MD059)\n- [rumdl](https://github.com/rvben/rumdl) - A fast Rust markdown linter that inspired our implementation approach\n\nWe aim to be compatible with markdownlint's rule definitions while adding mdBook-specific functionality.\n\n## License\n\nMIT OR Apache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshrotenberg%2Fmdbook-lint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshrotenberg%2Fmdbook-lint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshrotenberg%2Fmdbook-lint/lists"}