{"id":31032369,"url":"https://github.com/rvben/rumdl","last_synced_at":"2026-04-19T11:02:03.055Z","repository":{"id":280035925,"uuid":"940812004","full_name":"rvben/rumdl","owner":"rvben","description":"Fast Markdown linter and formatter written in Rust","archived":false,"fork":false,"pushed_at":"2026-04-12T20:42:16.000Z","size":11983,"stargazers_count":1019,"open_issues_count":2,"forks_count":44,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-04-12T22:59:42.380Z","etag":null,"topics":["cli","developer-tools","formatter","linter","markdown","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rvben.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","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},"funding":{"github":"rvben"}},"created_at":"2025-02-28T20:53:22.000Z","updated_at":"2026-04-12T22:43:17.000Z","dependencies_parsed_at":"2025-12-18T07:04:03.438Z","dependency_job_id":null,"html_url":"https://github.com/rvben/rumdl","commit_stats":null,"previous_names":["rvben/rumdl"],"tags_count":294,"template":false,"template_full_name":null,"purl":"pkg:github/rvben/rumdl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rvben%2Frumdl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rvben%2Frumdl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rvben%2Frumdl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rvben%2Frumdl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rvben","download_url":"https://codeload.github.com/rvben/rumdl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rvben%2Frumdl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32004043,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["cli","developer-tools","formatter","linter","markdown","rust"],"created_at":"2025-09-14T00:58:13.909Z","updated_at":"2026-04-19T11:02:03.042Z","avatar_url":"https://github.com/rvben.png","language":"Rust","funding_links":["https://github.com/sponsors/rvben"],"categories":["Rust","Development Tools","Linting, Formatting \u0026 Type Checking"],"sub_categories":[],"readme":"# rumdl - A high-performance Markdown linter, written in Rust\n\n\u003cdiv align=\"center\"\u003e\n\n![rumdl Logo](https://raw.githubusercontent.com/rvben/rumdl/main/assets/logo.png)\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/rvben/rumdl/ci.yml)](https://github.com/rvben/rumdl/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Crates.io](https://img.shields.io/crates/v/rumdl)](https://crates.io/crates/rumdl)\n[![PyPI](https://img.shields.io/pypi/v/rumdl)](https://pypi.org/project/rumdl/)\n[![GitHub release (latest by date)](https://img.shields.io/github/v/release/rvben/rumdl)](https://github.com/rvben/rumdl/releases/latest)\n[![GitHub stars](https://img.shields.io/github/stars/rvben/rumdl)](https://github.com/rvben/rumdl/stargazers)\n[![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord\u0026logoColor=white)](https://discord.gg/ADTJFSFUyn)\n[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github-sponsors)](https://github.com/sponsors/rvben)\n\n## A modern Markdown linter and formatter, built for speed with Rust\n\n| [**Docs**](https://rumdl.dev)\n| [**Rules**](https://rumdl.dev/rules)\n| [**Configuration**](https://rumdl.dev/global-settings)\n| [**Markdown Flavors**](https://rumdl.dev/flavors)\n| [**vs markdownlint**](https://rumdl.dev/markdownlint-comparison) |\n\n\u003c/div\u003e\n\n## Quick Start\n\n```bash\n# Install using Cargo\ncargo install rumdl\n\n# Lint Markdown files in the current directory\nrumdl check .\n\n# Format files (exits 0 on success, even if unfixable violations remain)\nrumdl fmt .\n\n# Auto-fix and report unfixable violations (exits 0 if all fixed, 1 if violations remain)\nrumdl check --fix .\n\n# Create a default configuration file\nrumdl init\n```\n\n## Overview\n\nrumdl is a high-performance Markdown linter and formatter that helps ensure consistency and best practices in your Markdown files. Inspired by [ruff](https://github.com/astral-sh/ruff) 's approach to\nPython linting, rumdl brings similar speed and developer experience improvements to the Markdown ecosystem.\n\nIt offers:\n\n- ⚡️ **Built for speed** with Rust - significantly faster than alternatives\n- 🔍 **71 lint rules** covering common Markdown issues\n- 🛠️ **Automatic formatting** with `--fix` for files and stdin/stdout\n- 📦 **Zero dependencies** - single binary with no runtime requirements\n- 🔧 **Highly configurable** with TOML-based config files\n- 🎯 **Multiple Markdown flavors** - [GFM, MkDocs, MDX, Quarto](docs/flavors.md) support with auto-detection\n- 🌐 **Multiple installation options** - Rust, Python, standalone binaries\n- 🐍 **Installable via pip** for Python users\n- 📏 **Modern CLI** with detailed error reporting\n- 🔄 **CI/CD friendly** with non-zero exit code on errors\n\n### Performance\n\nrumdl is designed for speed. Benchmarked on the [Rust Book](https://github.com/rust-lang/book) repository (478 markdown files, October 2025):\n\n![Cold start benchmark comparison](assets/benchmark.svg)\n\nWith intelligent caching, subsequent runs are even faster - rumdl only re-lints files that have changed, making it ideal for watch mode and editor integration.\n\n## Table of Contents\n\n- [Installation](#installation)\n  - [Using Homebrew (macOS/Linux)](#using-homebrew-macoslinux)\n  - [Using Cargo (Rust)](#using-cargo-rust)\n  - [Using npm](#using-npm)\n  - [Using pip (Python)](#using-pip-python)\n  - [Using uv](#using-uv)\n  - [Using mise](#using-mise)\n  - [Using Nix (macOS/Linux)](#using-nix-macoslinux)\n  - [Using Termux User Repository (TUR) (Android)](#using-termux-user-repository-tur-android)\n  - [Using pacman (Arch Linux)](#using-pacman-arch-linux)\n  - [Download binary](#download-binary)\n  - [Editor Plugins](#editor-plugins)\n- [Usage](#usage)\n  - [Stdin/Stdout Formatting](#stdinstdout-formatting)\n  - [Editor Integration](#editor-integration)\n- [Pre-commit Integration](#pre-commit-integration)\n  - [Excluding Files in Pre-commit](#excluding-files-in-pre-commit)\n- [CI/CD Integration](#cicd-integration)\n  - [GitHub Actions](#github-actions)\n    - [Inputs](#inputs)\n    - [Examples](#examples)\n- [Rules](#rules)\n- [Flavors](#flavors)\n  - [Supported Flavors](#supported-flavors)\n  - [Configuring Flavors](#configuring-flavors)\n- [Command-line Interface](#command-line-interface)\n  - [Commands](#commands)\n    - [`check [PATHS...]`](#check-paths)\n    - [`fmt [PATHS...]`](#fmt-paths)\n    - [`init [OPTIONS]`](#init-options)\n    - [`import \u003cFILE\u003e [OPTIONS]`](#import-file-options)\n    - [`rule [\u003crule\u003e]`](#rule-rule)\n    - [`config [OPTIONS] [COMMAND]`](#config-options-command)\n    - [`server [OPTIONS]`](#server-options)\n    - [`vscode [OPTIONS]`](#vscode-options)\n    - [`version`](#version)\n  - [Global Options](#global-options)\n  - [Exit Codes](#exit-codes)\n  - [Usage Examples](#usage-examples)\n- [LSP](#lsp)\n- [Configuration](#configuration)\n  - [Configuration Discovery](#configuration-discovery)\n  - [Editor Support (JSON Schema)](#editor-support-json-schema)\n  - [Global Configuration](#global-configuration)\n  - [Markdownlint Migration](#markdownlint-migration)\n  - [Inline Configuration](#inline-configuration)\n  - [Configuration File Example](#configuration-file-example)\n  - [Style Guide Presets](#style-guide-presets)\n  - [Initializing Configuration](#initializing-configuration)\n  - [Configuration in pyproject.toml](#configuration-in-pyprojecttoml)\n  - [Configuration Output](#configuration-output)\n    - [Effective Configuration (`rumdl config`)](#effective-configuration-rumdl-config)\n    - [Example output](#example-output)\n  - [Defaults Only (`rumdl config --defaults`)](#defaults-only-rumdl-config---defaults)\n  - [Non-Defaults Only (`rumdl config --no-defaults`)](#non-defaults-only-rumdl-config---no-defaults)\n- [Output Style](#output-style)\n  - [Output Format](#output-format)\n    - [Text Output (Default)](#text-output-default)\n    - [JSON Output](#json-output)\n- [Development](#development)\n  - [Prerequisites](#prerequisites)\n  - [Building](#building)\n  - [Testing](#testing)\n  - [JSON Schema Generation](#json-schema-generation)\n- [Used By](#used-by)\n- [Sponsors](#sponsors)\n- [License](#license)\n\n## Installation\n\nChoose the installation method that works best for you:\n\n### Using Homebrew (macOS/Linux)\n\n```bash\nbrew install rumdl\n```\n\n### Using Cargo (Rust)\n\n```bash\ncargo install rumdl\n```\n\n### Using npm\n\n```bash\nnpm install -g rumdl\n```\n\nOr as a dev dependency:\n\n```bash\nnpm install --save-dev rumdl\n```\n\n### Using pip (Python)\n\n```bash\npip install rumdl\n```\n\n### Using uv\n\nFor faster installation and better dependency management with [uv](https://github.com/astral-sh/uv):\n\n```bash\n# Install directly\nuv tool install rumdl\n\n# Or run without installing\nuvx rumdl check .\n```\n\n### Using mise\n\nFor dependency management with [mise](https://github.com/jdx/mise):\n\n```bash\n# List available versions\nmise ls-remote rumdl\n\n# Install the latest version\nmise install rumdl\n\n# Use a specific version for the project\nmise use rumdl@0.1.62\n```\n\n### Using Nix (macOS/Linux)\n\n```bash\nnix-channel --update\nnix-env --install --attr nixpkgs.rumdl\n```\n\nAlternatively, you can use flakes to run it without installation.\n\n```bash\nnix run --extra-experimental-features 'flakes nix-command' nixpkgs/nixpkgs-unstable#rumdl -- --version\n```\n\n### Using Termux User Repository (TUR) (Android)\n\nAfter enabling the TUR repo using\n\n```bash\npkg install tur-repo\n```\n\n```bash\npkg install rumdl\n```\n\n### Using pacman (Arch Linux)\n\nrumdl is available in the [official Arch Linux repositories](https://archlinux.org/packages/extra/x86_64/rumdl/):\n\n```bash\npacman -S rumdl\n```\n\n### Download binary\n\n```bash\n# Linux/macOS\ncurl -LsSf https://github.com/rvben/rumdl/releases/latest/download/rumdl-linux-x86_64.tar.gz | tar xzf - -C /usr/local/bin\n\n# Windows PowerShell\nInvoke-WebRequest -Uri \"https://github.com/rvben/rumdl/releases/latest/download/rumdl-windows-x86_64.zip\" -OutFile \"rumdl.zip\"\nExpand-Archive -Path \"rumdl.zip\" -DestinationPath \"$env:USERPROFILE\\.rumdl\"\n```\n\n### Editor Plugins\n\n| Editor                              | Install                                                                                          |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------ |\n| VS Code / Cursor / Windsurf         | `rumdl vscode` or [Marketplace](https://marketplace.visualstudio.com/items?itemName=rvben.rumdl) |\n| JetBrains (PyCharm, IntelliJ, etc.) | [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/29943-rumdl)                        |\n\nAll plugins provide real-time linting, formatting on save, hover documentation, and automatic configuration discovery.\n\n## Usage\n\nGetting started with rumdl is simple:\n\n```bash\n# Lint a single file\nrumdl check README.md\n\n# Lint all Markdown files in current directory and subdirectories\nrumdl check .\n\n# Format a specific file\nrumdl fmt README.md\n\n# Create a default configuration file\nrumdl init\n```\n\nCommon usage examples:\n\n```bash\n# Lint with custom configuration\nrumdl check --config my-config.toml docs/\n\n# Disable specific rules\nrumdl check --disable MD013,MD033 README.md\n\n# Enable only specific rules\nrumdl check --enable MD001,MD003 README.md\n\n# Exclude specific files/directories\nrumdl check --exclude \"node_modules,dist\" .\n\n# Include only specific files/directories\nrumdl check --include \"docs/*.md,README.md\" .\n\n# Watch mode for continuous linting\nrumdl check --watch docs/\n\n# Combine include and exclude patterns\nrumdl check --include \"docs/**/*.md\" --exclude \"docs/temp,docs/drafts\" .\n\n# Don't respect gitignore files (note: --respect-gitignore defaults to true)\nrumdl check --respect-gitignore=false .\n\n# Disable all exclude patterns from config\nrumdl check excluded.md --no-exclude\n```\n\n### Stdin/Stdout Formatting\n\nrumdl supports formatting via stdin/stdout, making it ideal for editor integrations and CI pipelines:\n\n```bash\n# Format content from stdin and output to stdout\ncat README.md | rumdl fmt --silent - \u003e README_formatted.md\n# Alternative: cat README.md | rumdl fmt --silent --stdin \u003e README_formatted.md\n\n# Use in a pipeline\necho \"# Title   \" | rumdl fmt --silent -\n# Output: # Title\n\n# Format clipboard content (macOS example)\npbpaste | rumdl fmt --silent - | pbcopy\n\n# Provide filename context for better error messages (useful for editor integrations)\ncat README.md | rumdl check - --stdin-filename README.md\n```\n\nUse `--silent` whenever stdout should contain only formatted Markdown. Plain `rumdl fmt -` may also emit remaining diagnostics.\n\n### Editor Integration\n\nFor editor integration, use stdin/stdout mode with the `--silent` flag when you want pure formatted output on stdout.\nUse `--quiet` if you still want diagnostics but want to suppress summary lines:\n\n```bash\n# Format selection in editor (example for vim)\n:'\u003c,'\u003e!rumdl fmt - --silent\n\n# Format entire buffer\n:%!rumdl fmt - --silent\n```\n\n## Pre-commit Integration\n\nYou can use `rumdl` as a pre-commit hook to check and format your Markdown files.\n\nThe recommended way is to use the official pre-commit hook repository:\n\n[rumdl-pre-commit repository](https://github.com/rvben/rumdl-pre-commit)\n\nAdd the following to your `.pre-commit-config.yaml`:\n\n```yaml\nrepos:\n  - repo: https://github.com/rvben/rumdl-pre-commit\n    rev: v0.1.62\n    hooks:\n      - id: rumdl      # Lint only (fails on issues)\n      - id: rumdl-fmt  # Auto-format and fail if issues remain\n```\n\nTwo hooks are available:\n\n- **`rumdl`** — Lints files and fails if any issues are found\n- **`rumdl-fmt`** — Auto-formats files and fails if unfixable violations remain (recommended for CI)\n\nWhen you run `pre-commit install` or `pre-commit run`, pre-commit will automatically install `rumdl` in an isolated Python environment using pip. You do **not** need to install rumdl manually.\n\n### Excluding Files in Pre-commit\n\nBy default, when pre-commit explicitly passes files to rumdl, the exclude patterns defined in your `.rumdl.toml` configuration file are respected.\n\nHowever, for pre-commit workflows where you want to include all files, even when they're excluded in the config, you can use the `--no-exclude` flag in your pre-commit config, e.g.:\n\n```yaml\nrepos:\n  - repo: https://github.com/rvben/rumdl-pre-commit\n    rev: v0.1.62\n    hooks:\n      - id: rumdl\n        args: [--no-exclude]  # Disable all exclude patterns\n```\n\n## CI/CD Integration\n\n### GitHub Actions\n\nWe have a companion Action you can use to integrate rumdl directly in your workflow:\n\n```yaml\njobs:\n  rumdl-check:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - uses: rvben/rumdl@v0\n```\n\nThe `v0` tag always points to the latest stable release, following GitHub Actions conventions.\n\n#### Inputs\n\n| Input         | Description                            | Default        |\n| ------------- | -------------------------------------- | -------------- |\n| `version`     | Version of rumdl to install            | latest         |\n| `path`        | Path to lint                           | workspace root |\n| `config`      | Path to config file                    | auto-detected  |\n| `report-type` | Output format: `logs` or `annotations` | `logs`         |\n\n#### Examples\n\n**Lint specific directory with pinned version:**\n\n```yaml\n- uses: rvben/rumdl@v0\n  with:\n    version: \"0.1.71\"\n    path: docs/\n```\n\n**Use custom config and show annotations in PR:**\n\n```yaml\n- uses: rvben/rumdl@v0\n  with:\n    config: .rumdl.toml\n    report-type: annotations\n```\n\nThe `annotations` report type displays issues directly in the PR's \"Files changed\" tab with error/warning severity levels and precise locations.\nThe action ref (`rvben/rumdl@v0`) selects the GitHub Action version, while the optional `version` input pins the `rumdl` CLI version installed inside the workflow.\n\n## Rules\n\nrumdl implements 71 lint rules for Markdown files. Here are some key rule categories:\n\n| Category       | Description                              | Example Rules       |\n| -------------- | ---------------------------------------- | ------------------- |\n| **Headings**   | Proper heading structure and formatting  | MD001, MD002, MD003 |\n| **Lists**      | Consistent list formatting and structure | MD004, MD005, MD007 |\n| **Whitespace** | Proper spacing and line length           | MD009, MD010, MD012 |\n| **Code**       | Code block formatting and language tags  | MD040, MD046, MD048 |\n| **Links**      | Proper link and reference formatting     | MD034, MD039, MD042 |\n| **Images**     | Image alt text and references            | MD045, MD052        |\n| **Style**      | Consistent style across document         | MD031, MD032, MD035 |\n\nFor a complete list of rules and their descriptions, see our [documentation](https://rumdl.dev/rules/) or run:\n\n```bash\nrumdl rule\n```\n\n## Flavors\n\nrumdl supports multiple Markdown flavors to accommodate different documentation systems. Each flavor adjusts rule behavior for syntax specific to that system, reducing false positives.\n\n### Supported Flavors\n\n| Flavor                                              | Use Case                     | Key Features                                      |\n| --------------------------------------------------- | ---------------------------- | ------------------------------------------------- |\n| [standard](docs/flavors/standard.md)                | Default Markdown             | CommonMark + GFM extensions (tables, task lists)  |\n| [gfm](docs/flavors/gfm.md)                          | GitHub Flavored Markdown     | Extended autolinks, security-sensitive HTML       |\n| [mkdocs](docs/flavors/mkdocs.md)                    | MkDocs / Material for MkDocs | Admonitions, content tabs, mkdocstrings           |\n| [mdx](docs/flavors/mdx.md)                          | MDX (JSX in Markdown)        | JSX components, ESM imports, expressions          |\n| [quarto](docs/flavors/quarto.md)                    | Quarto / RMarkdown           | Citations, shortcodes, executable code blocks     |\n\n### Configuring Flavors\n\nSet a global flavor in your configuration:\n\n```toml\n[global]\nflavor = \"mkdocs\"\n```\n\nOr configure per-file patterns:\n\n```toml\n[per-file-flavor]\n\"docs/**/*.md\" = \"mkdocs\"\n\"**/*.mdx\" = \"mdx\"\n\"**/*.qmd\" = \"quarto\"\n```\n\nWhen no flavor is configured, rumdl auto-detects based on file extension (`.mdx` → mdx, `.qmd`/`.Rmd` → quarto, `.md` → standard).\n\nFor complete flavor documentation, see the [Flavors Guide](docs/flavors.md).\n\n## Command-line Interface\n\n```bash\nrumdl \u003ccommand\u003e [options] [file or directory...]\n```\n\n### Commands\n\n#### `check [PATHS...]`\n\nLint Markdown files and print warnings/errors (main subcommand)\n\n**Arguments:**\n\n- `[PATHS...]`: Files or directories to lint. If provided, these paths take precedence over include patterns\n\n**Options:**\n\n- `-f, --fix`: Automatically fix issues where possible\n- `--diff`: Show diff of what would be fixed instead of fixing files\n- `-w, --watch`: Run in watch mode by re-running whenever files change\n- `-l, --list-rules`: List all available rules\n- `-d, --disable \u003crules\u003e`: Disable specific rules (comma-separated)\n- `-e, --enable \u003crules\u003e`: Enable only specific rules (comma-separated)\n- `--exclude \u003cpatterns\u003e`: Exclude specific files or directories (comma-separated glob patterns)\n- `--include \u003cpatterns\u003e`: Include only specific files or directories (comma-separated glob patterns)\n- `--respect-gitignore`: Respect .gitignore files when scanning directories (does not apply to explicitly provided paths)\n- `--no-exclude`: Disable all exclude patterns from config\n- `-v, --verbose`: Show detailed output\n- `--profile`: Show profiling information\n- `--statistics`: Show rule violation statistics summary\n- `-q, --quiet`: Print diagnostics, but suppress summary lines\n- `--output-format \u003cformat\u003e`: Output format for diagnostics\n- `--stdin`: Read from stdin instead of files\n\n#### `fmt [PATHS...]`\n\nFormat Markdown files and apply fixes. Unlike `check --fix`, `fmt` keeps formatter-style exit codes and exits 0 after successful formatting, making it ideal for editor integration.\n\n**Arguments:**\n\n- `[PATHS...]`: Files or directories to format. If provided, these paths take precedence over include patterns\n\n**Options:**\n\nAll the same options as `check` are available (except `--fix` which is always enabled), including:\n\n- `--stdin`: Format content from stdin and output to stdout\n- `-d, --disable \u003crules\u003e`: Disable specific rules during formatting\n- `-e, --enable \u003crules\u003e`: Format using only specific rules\n- `--exclude/--include`: Control which files to format\n- `-q, --quiet`: Print diagnostics, but suppress summary lines\n- `-s, --silent`: Suppress diagnostics and summaries for pure formatter output\n\n**Examples:**\n\n```bash\n# Format all Markdown files in current directory\nrumdl fmt\n\n# Format specific file\nrumdl fmt README.md\n\n# Format from stdin (using dash syntax)\ncat README.md | rumdl fmt --silent - \u003e formatted.md\n# Alternative: cat README.md | rumdl fmt --silent --stdin \u003e formatted.md\n```\n\n#### `init [OPTIONS]`\n\nCreate a default configuration file in the current directory\n\n**Options:**\n\n- `--pyproject`: Generate configuration for `pyproject.toml` instead of `.rumdl.toml`\n\n#### `import \u003cFILE\u003e [OPTIONS]`\n\nImport and convert markdownlint configuration files to rumdl format\n\n**Arguments:**\n\n- `\u003cFILE\u003e`: Path to markdownlint config file (JSON/JSONC/YAML)\n\n**Options:**\n\n- `-o, --output \u003cpath\u003e`: Output file path (default: `.rumdl.toml`)\n- `--format \u003cformat\u003e`: Output format: `toml` or `json` (default: `toml`)\n- `--dry-run`: Show converted config without writing to file\n\n#### `rule [\u003crule\u003e]`\n\nShow information about a rule or list all rules\n\n**Arguments:**\n\n- `[rule]`: Rule name or ID (optional). If provided, shows details for that rule. If omitted, lists all available rules\n\n**Useful options:**\n\n- `--list-categories`: List available rule categories and exit\n- `--category \u003cname\u003e`: Filter rules by category when listing\n- `--output-format \u003cformat\u003e`: Emit structured output such as `json` or `json-lines`\n- `--explain`: Include full documentation in `json` and `json-lines` output\n\n#### `config [OPTIONS] [COMMAND]`\n\nShow configuration or query a specific key\n\n**Options:**\n\n- `--defaults`: Show only the default configuration values\n- `--no-defaults`: Show only non-default configuration values (exclude defaults)\n- `--output \u003cformat\u003e`: Output format (e.g. `toml`, `json`)\n\n**Subcommands:**\n\n- `get \u003ckey\u003e`: Query a specific config key (e.g. `global.exclude` or `MD013.line_length`)\n- `file`: Show the absolute path of the configuration file that was loaded\n\n#### `server [OPTIONS]`\n\nStart the Language Server Protocol server for editor integration\n\n**Options:**\n\n- `--port \u003cPORT\u003e`: TCP port to listen on (for debugging)\n- `-v, --verbose`: Enable verbose logging\n\n#### `vscode [OPTIONS]`\n\nInstall the rumdl VS Code extension\n\n**Options:**\n\n- `--force`: Force reinstall even if already installed\n- `--update`: Update to the latest version (only if newer version is available)\n- `--status`: Show installation status without installing\n\n#### `version`\n\nShow version information\n\n### Global Options\n\nThese options are available for all commands:\n\n- `--color \u003cmode\u003e`: Control colored output: `auto` (default), `always`, `never`\n- `--config \u003cfile\u003e`: Path to configuration file\n- `--no-config`: Ignore all configuration files and use built-in defaults\n- `--isolated`: Hidden compatibility alias for `--no-config`\n\n### Exit Codes\n\n- `0`: Success (no violations found, or all violations were fixed)\n- `1`: Violations found (or remain after `--fix`)\n- `2`: Tool error\n\n**Note:** `rumdl fmt` exits 0 on successful formatting (even if unfixable violations remain), making it compatible with editor integrations. `rumdl check --fix` exits 0 if all violations are fixed, or\n1 if violations remain after fixing (useful for pre-commit hooks and CI/CD).\n\n### Usage Examples\n\n```bash\n# Lint all Markdown files in the current directory\nrumdl check .\n\n# Format files (exits 0 on success, even if unfixable violations remain)\nrumdl fmt .\n\n# Auto-fix and report unfixable violations (exits 0 if all fixed, 1 if violations remain)\nrumdl check --fix .\n\n# Preview what would be fixed without modifying files\nrumdl check --diff .\n\n# Create a default configuration file\nrumdl init\n\n# Create or update a pyproject.toml file with rumdl configuration\nrumdl init --pyproject\n\n# Import a markdownlint config file\nrumdl import .markdownlint.json\n\n# Convert markdownlint config to JSON format\nrumdl import --format json .markdownlint.yaml --output rumdl-config.json\n\n# Preview conversion without writing file\nrumdl import --dry-run .markdownlint.json\n\n# Show information about a specific rule\nrumdl rule MD013\n\n# List all available rules\nrumdl rule\n\n# Query a specific config key\nrumdl config get global.exclude\n\n# Show the path of the loaded configuration file\nrumdl config file\n\n# Show configuration as JSON instead of the default format\nrumdl config --output json\n\n# Show only non-default configuration values\nrumdl config --no-defaults\n\n# Lint content from stdin\necho \"# My Heading\" | rumdl check --stdin\n\n# Get JSON output for integration with other tools\nrumdl check --output-format json README.md\n\n# Show statistics summary of rule violations\nrumdl check --statistics .\n\n# Disable colors in output\nrumdl check --color never README.md\n\n# Use built-in defaults, ignoring all config files\nrumdl check --no-config README.md\n\n# Show version information\nrumdl version\n```\n\n## LSP\n\nrumdl is also available as an LSP server for editor integration.\n\nFor editors that support generic LSP configuration, the minimal stdio setup is:\n\n```toml\ncommand = [\"rumdl\", \"server\"]\n```\n\nFor editor-specific information on setting up the LSP, refer to our [LSP documentation](https://rumdl.dev/lsp/)\n\n## Configuration\n\nrumdl can be configured in several ways:\n\n1. Using a `.rumdl.toml` or `rumdl.toml` file in your project directory or parent directories\n2. Using a `\u003cproject\u003e/.config/rumdl.toml` file (following the [config-dir convention](https://github.com/pi0/config-dir))\n3. Using the `[tool.rumdl]` section in your project's `pyproject.toml` file (for Python projects)\n4. Using command-line arguments\n5. Using a **global user config** at `~/.config/rumdl/rumdl.toml` (see [Global Configuration](#global-configuration) below)\n6. **Automatic markdownlint compatibility**: rumdl automatically discovers and loads existing markdownlint config files (`.markdownlint.json`, `.markdownlint.yaml`, etc.)\n\n### Configuration Discovery\n\nrumdl automatically searches for configuration files by traversing up the directory tree from the current working directory, similar to tools like `git` , `ruff` , and `eslint` . This means you can\nrun rumdl from any subdirectory of your project and it will find the configuration file at the project root.\n\nThe search follows these rules:\n\n- Searches upward for `.rumdl.toml`, `rumdl.toml`, `\u003cdir\u003e/.config/rumdl.toml`, or `pyproject.toml` (with `[tool.rumdl]` section)\n- Precedence order: `.rumdl.toml` \u003e `rumdl.toml` \u003e `\u003cdir\u003e/.config/rumdl.toml` \u003e `pyproject.toml`\n- Stops at the first configuration file found\n- Stops searching when it encounters a `.git` directory (project boundary)\n- Maximum traversal depth of 100 directories\n- Falls back to markdownlint config files (`.markdownlint.yaml`, etc.) using the same upward traversal\n- Falls back to user configuration if no project configuration is found (see Global Configuration below)\n\n#### Per-Directory Configuration\n\nWhen running `rumdl check .` from the project root, rumdl resolves configuration\non a **per-directory** basis. Files in subdirectories with their own `.rumdl.toml`\nuse that config instead of the root config. This matches the behavior of\n[Ruff](https://docs.astral.sh/ruff/) and\n[markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2).\n\nSubdirectory configs are **standalone** by default. Use `extends` to inherit from a parent config:\n\n```toml\n# docs/.rumdl.toml — inherits root config, overrides line-length\nextends = \"../.rumdl.toml\"\n\n[global]\nline-length = 120\n```\n\nPer-directory resolution is disabled when `--config` or `--no-config` is used (`--isolated` is still accepted as a compatibility alias).\n\nTo disable all configuration discovery and use only built-in defaults, use the `--no-config` flag:\n\n```bash\n# Use discovered configuration (default behavior)\nrumdl check .\n\n# Ignore all configuration files\nrumdl check --no-config .\n```\n\n### Editor Support (JSON Schema)\n\nrumdl provides a JSON Schema for `.rumdl.toml` configuration files, enabling autocomplete, validation, and inline documentation in supported editors like VS Code, IntelliJ IDEA, and others.\n\nThe schema is available at `https://raw.githubusercontent.com/rvben/rumdl/main/rumdl.schema.json`.\n\n**Automatic Setup (via SchemaStore):**\n\nThe schema is registered with [SchemaStore](https://www.schemastore.org/), so editors with TOML support will automatically provide autocomplete and validation for `.rumdl.toml` and `rumdl.toml` files.\n\n**VS Code:** Install the \"Even Better TOML\" extension - schema association is automatic.\n\n**Manual Schema Association:**\n\nIf your editor doesn't support SchemaStore, associate this schema URL with `.rumdl.toml` or `rumdl.toml` in the editor's TOML schema settings:\n\n`https://raw.githubusercontent.com/rvben/rumdl/main/rumdl.schema.json`\n\n### Global Configuration\n\nWhen no project configuration is found, rumdl will check for a user-level configuration file in your platform's standard config directory:\n\n**Location:**\n\n- **Linux/macOS**: `~/.config/rumdl/` (respects `XDG_CONFIG_HOME` if set)\n- **Windows**: `%APPDATA%\\rumdl\\`\n\n**Files checked (in order):**\n\n1. `.rumdl.toml`\n2. `rumdl.toml`\n3. `pyproject.toml` (must contain `[tool.rumdl]` section)\n\nThis allows you to set personal preferences that apply to all projects without local configuration.\n\n**Example:** Create `~/.config/rumdl/rumdl.toml`:\n\n```toml\n[global]\nline-length = 100\ndisable = [\"MD013\", \"MD041\"]\n\n[MD007]\nindent = 2\n```\n\n**Note:** User configuration is only used when no project configuration exists. Project configurations always take precedence.\n\n### Markdownlint Migration\n\nrumdl provides seamless compatibility with existing markdownlint configurations:\n\n**Automatic Discovery**: rumdl automatically detects and loads markdownlint config files by traversing up the directory tree (just like `.rumdl.toml`):\n\n- `.markdownlint.json` / `.markdownlint.jsonc`\n- `.markdownlint.yaml` / `.markdownlint.yml`\n- `markdownlint.json` / `markdownlint.yaml`\n\nThis means you can place a `.markdownlint.yaml` at your project root and run rumdl from any subdirectory - it will find and use the config automatically.\n\n**Explicit Import**: Convert markdownlint configs to rumdl format:\n\n```bash\n# Convert to .rumdl.toml\nrumdl import .markdownlint.json\n\n# Convert to JSON format\nrumdl import --format json .markdownlint.yaml --output config.json\n\n# Preview conversion\nrumdl import --dry-run .markdownlint.json\n```\n\nFor comprehensive documentation on global settings (file selection, rule enablement, etc.), see our [Global Settings Reference](docs/global-settings.md).\n\n### Inline Configuration\n\nrumdl supports inline HTML comments to disable or configure rules for specific sections of your Markdown files. This is useful for making exceptions without changing global configuration:\n\n```markdown\n\u003c!-- rumdl-disable MD013 --\u003e\nThis line can be as long as needed without triggering the line length rule.\n\u003c!-- rumdl-enable MD013 --\u003e\n```\n\nNote: `markdownlint-disable`/`markdownlint-enable` comments are also supported for compatibility with existing markdownlint configurations.\n\nFor complete documentation on inline configuration options, see our [Inline Configuration Reference](docs/inline-configuration.md).\n\n### Configuration File Example\n\nHere's an example `.rumdl.toml` configuration file:\n\n```toml\n[global]\nline-length = 100\nexclude = [\"node_modules\", \"build\", \"dist\"]\nrespect-gitignore = true\nflavor = \"mkdocs\"  # Use MkDocs flavor (see Flavors section)\ndisable = [\"MD013\", \"MD033\"]\n\n# Per-file flavor overrides\n[per-file-flavor]\n\"**/*.mdx\" = \"mdx\"\n\n# Disable specific rules for specific files\n[per-file-ignores]\n\"README.md\" = [\"MD033\"]  # Allow HTML in README\n\"SUMMARY.md\" = [\"MD025\"]  # Allow multiple H1 in table of contents\n\"docs/api/**/*.md\" = [\"MD013\", \"MD041\"]  # Relax rules for generated docs\n\n# Configure individual rules\n[MD007]\nindent = 2\n\n[MD013]\nline-length = 100\ncode-blocks = false\ntables = false\nreflow = true  # Enable automatic line wrapping (required for --fix)\n\n[MD025]\nlevel = 1\nfront-matter-title = \"title\"\n\n[MD044]\nnames = [\"rumdl\", \"Markdown\", \"GitHub\"]\n\n[MD048]\ncode-fence-style = \"backtick\"\n\n# Code block tools (optional)\n[code-block-tools]\nenabled = true\nnormalize-language = \"linguist\"\non-error = \"warn\"\ntimeout = 30000\n\n[code-block-tools.language-aliases]\npy = \"python\"\nbash = \"shell\"\n\n[code-block-tools.languages.python]\nlint = [\"ruff:check\"]\nformat = [\"ruff:format\"]\n```\n\n### Style Guide Presets\n\nReady-to-use configurations for popular style guides are available in the [`examples/`](examples/) directory:\n\n- **[Google Style](examples/google-style.rumdl.toml)** - Google's Markdown style guide\n- **[Prettier-compatible](examples/prettier-compatible.rumdl.toml)** - Aligns with Prettier's markdown formatting\n\nCopy one to your project as `.rumdl.toml` to use it.\n\n### Initializing Configuration\n\nTo create a configuration file, use the `init` command:\n\n```bash\n# Create a .rumdl.toml file (for any project)\nrumdl init\n\n# Create or update a pyproject.toml file with rumdl configuration (for Python projects)\nrumdl init --pyproject\n```\n\n### Configuration in pyproject.toml\n\nFor Python projects, you can include rumdl configuration in your `pyproject.toml` file, keeping all project configuration in one place. Example:\n\n```toml\n[tool.rumdl]\n# Global options at root level\nline-length = 100\ndisable = [\"MD033\"]\ninclude = [\"docs/*.md\", \"README.md\"]\nexclude = [\".git\", \"node_modules\"]\nrespect-gitignore = true\n\n# Rule-specific configuration\n[tool.rumdl.MD013]\ncode_blocks = false\ntables = false\n\n[tool.rumdl.MD044]\nnames = [\"rumdl\", \"Markdown\", \"GitHub\"]\n```\n\nBoth kebab-case (`line-length`, `respect-gitignore`) and snake_case (`line_length`, `respect_gitignore`) formats are supported for compatibility with different Python tooling conventions.\n\n### Configuration Output\n\n#### Effective Configuration (`rumdl config`)\n\nThe `rumdl config` command prints the **full effective configuration** (defaults + all overrides), showing every key and its value, annotated with the source of each value. The output is colorized and\nthe `[from ...]` annotation is globally aligned for easy scanning.\n\n#### Example output\n\n```text\n[global]\n  enable             = []                             [from default]\n  disable            = [\"MD033\"]                      [from .rumdl.toml]\n  include            = [\"README.md\"]                  [from .rumdl.toml]\n  respect_gitignore  = true                           [from .rumdl.toml]\n\n[MD013]\n  line_length        = 200                            [from .rumdl.toml]\n  code_blocks        = true                           [from .rumdl.toml]\n  ...\n```\n\n- ** Keys** are cyan, **values** are yellow, and the `[from ...]` annotation is colored by source:\n  - Green: CLI\n  - Blue: `.rumdl.toml`\n  - Magenta: `pyproject.toml`\n  - Yellow: default\n- The `[from ...]` column is aligned across all sections.\n\n### Defaults Only (`rumdl config --defaults`)\n\nThe `rumdl config --defaults` command shows only the default configuration values, useful for understanding what the built-in defaults are.\n\n### Non-Defaults Only (`rumdl config --no-defaults`)\n\nThe `rumdl config --no-defaults` command shows only configuration values that differ from defaults, making it easy to see what you've customized. This is particularly useful when you want to see only\nyour project-specific or user-specific overrides without the noise of default values.\n\n**Example:**\n\n```bash\n$ rumdl config --no-defaults\n[global]\ndisable = [\"MD013\"]                    [from project config]\nline_length = 100                      [from pyproject.toml]\n\n[MD004]\nstyle = \"asterisk\"                     [from project config]\n```\n\nThis helps you quickly identify what customizations you've made to the default configuration.\n\nThe `--defaults` flag prints only the default configuration as TOML, suitable for copy-paste or reference:\n\n```toml\n[global]\nenable = []\ndisable = []\nexclude = []\ninclude = []\nrespect_gitignore = true\nforce_exclude = false  # Set to true to exclude files even when explicitly specified\n\n[MD013]\nline_length = 80\ncode_blocks = true\n...\n```\n\n## Output Style\n\nrumdl produces clean, colorized output similar to modern linting tools:\n\n```text\nREADME.md:12:1: [MD022] Headings should be surrounded by blank lines [*]\nREADME.md:24:5: [MD037] Spaces inside emphasis markers: \"* incorrect *\" [*]\nREADME.md:31:76: [MD013] Line length exceeds 80 characters\nREADME.md:42:3: [MD010] Hard tabs found, use spaces instead [*]\n```\n\nWhen running with `--fix`, rumdl shows which issues were fixed:\n\n```text\nREADME.md:12:1: [MD022] Headings should be surrounded by blank lines [fixed]\nREADME.md:24:5: [MD037] Spaces inside emphasis markers: \"* incorrect *\" [fixed]\nREADME.md:42:3: [MD010] Hard tabs found, use spaces instead [fixed]\n\nFixed 3 issues in 1 file\n```\n\nFor a more detailed view, use the `--verbose` option:\n\n```text\n✓ No issues found in CONTRIBUTING.md\nREADME.md:12:1: [MD022] Headings should be surrounded by blank lines [*]\nREADME.md:24:5: [MD037] Spaces inside emphasis markers: \"* incorrect *\" [*]\nREADME.md:42:3: [MD010] Hard tabs found, use spaces instead [*]\n\nFound 3 issues in 1 file (2 files checked)\nRun `rumdl fmt` to automatically fix issues\n```\n\n### Output Format\n\n#### Text Output (Default)\n\nrumdl uses a consistent output format for all issues:\n\n```text\n{file}:{line}:{column}: [{rule_id}] {message} [{fix_indicator}]\n```\n\nThe output is colorized by default:\n\n- Filenames appear in blue and underlined\n- Line and column numbers appear in cyan\n- Rule IDs appear in yellow\n- Error messages appear in white\n- Fixable issues are marked with `[*]` in green\n- Fixed issues are marked with `[fixed]` in green\n\n#### JSON Output\n\nFor integration with other tools and automation, use `--output-format json`:\n\n```bash\nrumdl check --output-format json README.md\n```\n\nThis produces structured JSON output:\n\n```json\n{\n  \"summary\": {\n    \"total_files\": 1,\n    \"files_with_issues\": 1,\n    \"total_issues\": 2,\n    \"fixable_issues\": 1\n  },\n  \"files\": [\n    {\n      \"path\": \"README.md\",\n      \"issues\": [\n        {\n          \"line\": 12,\n          \"column\": 1,\n          \"rule\": \"MD022\",\n          \"message\": \"Headings should be surrounded by blank lines\",\n          \"fixable\": true,\n          \"severity\": \"error\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n## Development\n\n### Prerequisites\n\n- Rust 1.91 or higher\n- Make (for development commands)\n\n### Building\n\n```bash\nmake build\n```\n\n### Testing\n\n```bash\nmake test\n```\n\n### JSON Schema Generation\n\nIf you modify the configuration structures in `src/config.rs`, regenerate the JSON schema:\n\n```bash\n# Generate/update the schema\nmake schema\n# Or: rumdl schema generate\n\n# Check if schema is up-to-date (useful in CI)\nmake check-schema\n# Or: rumdl schema check\n\n# Print schema to stdout\nrumdl schema print\n```\n\nThe schema is automatically generated from the Rust types using `schemars` and should be kept in sync with the configuration structures.\n\n## Used By\n\nrumdl is used by these notable open source projects:\n\n| Project                                                                                     | Stars                                                                                              |\n| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |\n| [apache/lucene](https://github.com/apache/lucene)                                           | ![stars](https://img.shields.io/github/stars/apache/lucene?style=flat-square)                      |\n| [beeware/briefcase](https://github.com/beeware/briefcase)                                   | ![stars](https://img.shields.io/github/stars/beeware/briefcase?style=flat-square)                  |\n| [beeware/toga](https://github.com/beeware/toga)                                             | ![stars](https://img.shields.io/github/stars/beeware/toga?style=flat-square)                       |\n| [chrisgrieser/nvim-scissors](https://github.com/chrisgrieser/nvim-scissors)                 | ![stars](https://img.shields.io/github/stars/chrisgrieser/nvim-scissors?style=flat-square)         |\n| [chrisgrieser/nvim-spider](https://github.com/chrisgrieser/nvim-spider)                     | ![stars](https://img.shields.io/github/stars/chrisgrieser/nvim-spider?style=flat-square)           |\n| [chrisgrieser/nvim-various-textobjs](https://github.com/chrisgrieser/nvim-various-textobjs) | ![stars](https://img.shields.io/github/stars/chrisgrieser/nvim-various-textobjs?style=flat-square) |\n| [chrisgrieser/shimmering-focus](https://github.com/chrisgrieser/shimmering-focus)           | ![stars](https://img.shields.io/github/stars/chrisgrieser/shimmering-focus?style=flat-square)      |\n| [chrisgrieser/shimmering-obsidian](https://github.com/chrisgrieser/shimmering-obsidian)     | ![stars](https://img.shields.io/github/stars/chrisgrieser/shimmering-obsidian?style=flat-square)   |\n| [matrix-org/matrix.org](https://github.com/matrix-org/matrix.org)                           | ![stars](https://img.shields.io/github/stars/matrix-org/matrix.org?style=flat-square)              |\n| [mikavilpas/yazi.nvim](https://github.com/mikavilpas/yazi.nvim)                             | ![stars](https://img.shields.io/github/stars/mikavilpas/yazi.nvim?style=flat-square)               |\n| [PyO3/pyo3](https://github.com/PyO3/pyo3)                                                   | ![stars](https://img.shields.io/github/stars/PyO3/pyo3?style=flat-square)                          |\n| [scop/bash-completion](https://github.com/scop/bash-completion)                             | ![stars](https://img.shields.io/github/stars/scop/bash-completion?style=flat-square)               |\n| [Ulauncher/Ulauncher](https://github.com/Ulauncher/Ulauncher)                               | ![stars](https://img.shields.io/github/stars/Ulauncher/Ulauncher?style=flat-square)                |\n\n*Using rumdl? [Let us know!](https://github.com/rvben/rumdl/issues/307)*\n\n## Sponsors\n\nrumdl is free and open source. If it saves you time, consider [sponsoring the project](https://github.com/sponsors/rvben).\n\n\u003c!-- sponsors --\u003e\n- [David Hewitt](https://github.com/davidhewitt)\n\u003c!-- sponsors --\u003e\n\n## License\n\nrumdl is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frvben%2Frumdl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frvben%2Frumdl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frvben%2Frumdl/lists"}