katana-markdown-linter

A markdownlint-compatible Rust engine, kml CLI, formatter, safe fixer, editor server, and agent-ready MCP server.

Installation | CLI Usage | Library API | Editor Integration | MCP Server

What is kml

katana-markdown-linter is a fast Markdown lint engine for technical writing, specification documents, and AI-agent-assisted documentation workflows.

The project shares the KatanA visual identity, but keeps a standalone boundary: the crate, CLI, wrappers, editor server, and MCP server do not depend on KatanA Desktop.

Features

• markdownlint-compatible checks for the active upstream rule catalog
• Safe fixes for low-risk rule violations and explicit opt-in unsafe fixes
• Formatter mode for layout normalization without changing author intent
• Embeddable Rust API for applications that need linting or fixing in-process
• kml CLI with JSON output, stdin support, ignore handling, and statistics
• Editor integration through a stdio Language Server Protocol server
• MCP server for agents and tools that need structured lint access
• Multi-channel distribution through Cargo, GitHub Releases, npm, PyPI, and Homebrew

Library API

Use the crate directly when embedding linting into another Rust application.

• lint(content, options)
• fix(content, options)
• available_rules()
• localized_available_rules(language_code)
• implemented_rules()
• missing_rules()
• rule_catalog()
• localized_rule_catalog(language_code)
• resolve_locale_code(language_code)
• resolve_locale_code_or(language_code, fallback)
• localized_rule_description(rule_id, fallback_description, language_code)
• supported_locales()
• upstream::get_rule_documentation(rule_id, locale)
• MarkdownLintConfig
• MarkdownLintConfig::schema()
• MarkdownLintConfig::to_lint_options()

available_rules() returns canonical English metadata. For user-facing rule catalogs, call localized_available_rules(language_code), localized_rule_catalog(language_code), RuleMeta::localized_description(...), or localized_rule_description(...) so applications can pass UI language codes without reimplementing kml's fallback policy.

Locale is #[non_exhaustive] from v0.6.0. Consumers that match on Locale should include a wildcard arm and prefer resolve_locale_code(...) or resolve_locale_code_or(...) for UI language strings. Rule descriptions and rule Markdown documentation are localized for en, ja, zh-CN, zh-TW, ko, pt, fr, de, es, and it.

Minimal embedding examples are available under examples/:

• embedding.rs: string checks, file tree checks, string fixes, config loading and config-to-options conversion

Installation

Cargo

cargo install katana-markdown-linter

The binary target is kml. Use Cargo when you want the Rust crate and CLI from the same channel.

npm

The npm package is a thin launcher that downloads the matching GitHub Release archive for kml, kml-mcp, or kml-mcp-remote on first use:

npm install -g katana-markdown-linter
kml version

Use npx for one-off runs:

npx --yes katana-markdown-linter@0.19.4 check README.md
npx --yes katana-markdown-linter@0.19.4 kml-mcp --workspace-root /absolute/path/to/workspace
bunx --package katana-markdown-linter@0.19.4 kml-mcp --workspace-root /absolute/path/to/workspace

PyPI

The PyPI package is a thin Python launcher that downloads the matching GitHub Release archive for kml, kml-mcp, or kml-mcp-remote on first use:

pipx install katana-markdown-linter
kml version

If you do not use pipx, install with your normal Python environment manager.

Use uvx for one-off runs without installing the launcher into your active environment:

uvx --from katana-markdown-linter==0.19.4 kml check README.md
uvx --from katana-markdown-linter==0.19.4 kml-mcp --workspace-root /absolute/path/to/workspace

GitHub Releases

Standalone kml archives are attached to GitHub Releases. Choose the archive that matches your Rust target triple:

curl -LO https://github.com/HiroyukiFuruno/katana-markdown-linter/releases/download/v0.19.4/kml-v0.19.4-aarch64-apple-darwin.tar.gz
curl -LO https://github.com/HiroyukiFuruno/katana-markdown-linter/releases/download/v0.19.4/kml-v0.19.4-aarch64-apple-darwin.tar.gz.sha256
shasum -a 256 -c kml-v0.19.4-aarch64-apple-darwin.tar.gz.sha256
tar -xzf kml-v0.19.4-aarch64-apple-darwin.tar.gz

Homebrew

Homebrew formula publication is part of the release flow. Install with:

brew install HiroyukiFuruno/katana/kml

VS Code

Install the KatanA Markdown Linter extension from the VS Code Marketplace or sideload the local package. The extension acts as a thin wrapper around the kml lsp server and verifies version compatibility on startup.

# Sideload for MVP testing
cd editors/vscode
npm install
npm run compile
code --extensionDevelopmentPath=$PWD

Zed

Install the KatanA Markdown Linter extension from the Zed extension registry or sideload from the repository. The extension registers kml lsp as a Markdown language server and supports custom binary paths.

# Sideload for MVP testing
# Use the "zed: install dev extension" action in Zed
# and select the 'editors/zed' directory.

GitHub Actions

Use the repository action to run kml in CI without writing install steps:

- uses: actions/checkout@v5
- uses: HiroyukiFuruno/katana-markdown-linter@v0.18.0
  with: { version: "0.18.0", command: check, paths: "README.md\ndocs", config: .markdownlint.json }

Pin the action tag and version together for reproducible runs. The action installs kml from crates.io by default. Repository-local smoke tests can set install-source: path and path: ..

extra-args accepts one argument per line, so flags that take values must use separate lines.

CLI Usage

kml check
kml check --locale en
kml check -l ja
kml --locale ja help
kml fix
kml fmt
kml check --fix
kml fix --unsafe --yes README.md
kml check --fix --unsafe --yes README.md
kml check README.md
kml check --file README.md
kml check --output json "docs/**/*.md"
kml check --format json "docs/**/*.md"
kml check --ignore-config-errors README.md
kml check --stdin
kml fix --stdin
kml check --include "**/*.md" --exclude "target/**"
kml check --include-reserved node_modules
kml check --no-ignore --force-exclude --exclude "vendor/**" vendor/README.md
kml check --statistics --quiet
kml fix --diff README.md
kml rule
kml rule --locale ja
kml rule --locale fr
kml rule MD013
kml rule MD013 --locale ja --output json
kml config file
kml config get --output json
kml config schema
kml --help
kml -h
kml help
kml check --help
kml check -h
kml version
kml --version
kml -v
kml fix --config .markdownlint.json README.md
kml init-config

When no files are provided, kml check, kml fix, and kml fmt recursively process Markdown files under the current directory. Use --file to make single-file intent explicit.

check reports diagnostics and exits with 1 when lint violations are found. fix and check --fix apply safe lint-driven fixes and exit with 1 if violations remain after rewriting. fmt is a layout formatter for indentation and newline normalization; it exits with 0 after successful formatting even when unrelated lint diagnostics would still be reported by check. Filesystem or configuration errors exit with 2.

fmt currently normalizes CRLF/CR line endings to LF, final newlines, repeated blank lines, blank lines around headings/fences/lists/tables, and safe list indentation/list-marker spacing. It does not reflow paragraphs, change heading or emphasis style, change URL/table style, remove trailing spaces, or apply unsafe fixes by default.

Unsafe fixes require explicit opt-in for fix and check --fix. Interactive use prompts with [Y/n]; non-interactive use must pass --unsafe --yes.

--output json is the preferred JSON output flag. --format json remains a compatibility alias. Fix-mode JSON includes per-file fix_details so applied rules can be compared with pre-fix diagnostics and rewritten file diffs.

--stdin reads Markdown from standard input. check --stdin reports diagnostics against <stdin>; fix --stdin writes fixed Markdown to stdout; fmt --stdin writes formatted Markdown only to stdout.

Directory scans respect gitignore files by default. Use --no-ignore to include ignored paths everywhere, or --include-ignored to include ignored paths only under explicit directory inputs such as .agents. Reserved directories such as .git, node_modules, target, dist, build, and coverage are skipped by default even without gitignore entries; use --include-reserved only when you intentionally want to scan them. Project-specific generated or agent directories should be covered by gitignore or --exclude. --exclude filters discovered files; explicit files are kept unless --force-exclude is also set.

Invoking kml without a command prints global help. kml help, kml --help, kml -h, and kml <command> --help print help without scanning files.

--locale <locale> and -l <locale> select user-facing CLI message and help text locale. Supported values resolve to en, ja, zh-CN, zh-TW, ko, pt, fr, de, es, and it, including common region forms such as fr-FR, pt-BR, or ko-KR. When omitted, kml reads OS locale environment variables and falls back to English if the locale is unavailable or unsupported. Explicit unsupported locales fail with a CLI error. --local is accepted as a backward-compatible alias for v0.4.0 users.

kml rule and kml rule <id> also honor --locale. Text output uses localized rule descriptions, and JSON output includes both description (localized) and english_description (canonical English).

Rule Map

kml ships lint checks for the active markdownlint rule catalog. The rule IDs below match the public catalog returned by available_rules() and kml rule --output json; state columns describe fixture-backed implementation status. Run kml rule MD013 to inspect one rule with its upstream documentation URL.

The short version:

Safe fixes are intentionally conservative. Implemented subset means kml rewrites fixture-locked, low-risk violation forms for that rule. Diagnostic only means checks are implemented, but safe fixes are not provided. Manual intent required means an automatic rewrite would choose author intent. Not applicable means no separate unsafe candidate is currently identified beyond the safe-fix policy. Deleted rows are historical markdownlint IDs that are not part of the active upstream rule catalog.

Configuration

The crate reads and writes markdownlint-compatible JSON and JSONC configuration files:

• .markdownlint.json
• .markdownlint.jsonc

Use kml init-config to create a default .markdownlint.json.

Use kml config schema to print the JSON Schema used by editor integration and configuration validation. The stable schema ID is https://schemas.katana.tools/kml/markdownlint.schema.json.

Configuration errors stop check, fix, and fmt before file diagnostics are reported. Fix the config first, or pass --ignore-config-errors when you explicitly want invalid config entries ignored for that run. Official markdownlint aliases such as first-line-h1, first-line-heading, no-duplicate-heading, and no-inline-html are accepted.

Editor Integration

kml lsp starts a stdio Language Server Protocol server for Markdown diagnostics, formatting, range formatting, and safe quick fixes. VS Code, Zed, and Neovim setup examples are documented in docs/editor-integration.md.

Quality Gates

Use just check for the default local gate. It runs format, Clippy, AST lint, and tests.

Use just dogfood to run kml against this repository's Markdown documentation without modifying files. Use just dogfood-fix only when you intend to apply safe Markdown fixes. Archived OpenSpec documents are excluded from the default dogfood targets; run just dogfood-archive to check them explicitly.

Use just examples to compile the public Rust embedding examples.

Quality gate details, CI required checks, coverage modes, and release readiness are documented in docs/quality-gates.md.

Distribution channel status and deferral notes are documented in docs/distribution.md.

MCP Server

kml-mcp is an optional MCP server for agents and editors that want structured library access over stdio while keeping the core crate independent from MCP dependencies.

Build or install it with the mcp feature:

cargo build --bin kml-mcp --features mcp --locked
cargo install katana-markdown-linter --locked --features mcp --bin kml-mcp

After v0.19.3, the npm and PyPI wrappers can launch the same stdio server without a Rust toolchain:

npx --yes katana-markdown-linter@0.19.4 kml-mcp --workspace-root /absolute/path/to/workspace
bunx --package katana-markdown-linter@0.19.4 kml-mcp --workspace-root /absolute/path/to/workspace
uvx --from katana-markdown-linter==0.19.4 kml-mcp --workspace-root /absolute/path/to/workspace

The server exposes text, config, rule metadata, and workspace-safe file tools:

• check_text
• fix_text
• config_validate
• rule_list
• rule_get
• check_file
• check_directory
• fix_file_preview
• fix_file_apply

Workspace paths must stay under the configured --workspace-root. File writes are limited to fix_file_apply and require apply: true; no directory apply tool is exposed.

Run just mcp-stdio-smoke to exercise the installed MCP server through JSON-RPC stdio calls.

kml-mcp-remote is a separate self-hosted Streamable HTTP server for API-hosted LLM clients that cannot launch a stdio subprocess. It exposes text-only tools by default and does not expose workspace file tools:

cargo build --bin kml-mcp-remote --features mcp-remote --locked
KML_MCP_REMOTE_TOKEN=change-me target/debug/kml-mcp-remote

Wrapper entrypoints are available for self-hosted remote MCP as well:

KML_MCP_REMOTE_TOKEN=change-me \
  npx --yes --package katana-markdown-linter@0.19.4 kml-mcp-remote
KML_MCP_REMOTE_TOKEN=change-me \
  uvx --from katana-markdown-linter==0.19.4 kml-mcp-remote

Run just mcp-remote-smoke to verify bearer authentication, text-only tool capabilities, text diagnostics, and the request body limit.

v0.14.0 introduced a Linux MCPB bundle from GitHub Releases and MCP Registry metadata for the local stdio server. Build the bundle and exercise the bundled kml-mcp binary before publication:

just VERSION=v0.19.4 mcpb-smoke

See MCP server documentation, the remote MCP deployment guide, the MCP distribution plan, and the earlier MCP integration evaluation.

Release Policy

• The library API is the primary contract.
• The CLI is a thin wrapper over the library.
• Cargo.toml package version is the release version source of truth.
• Run just VERSION=vX.Y.Z release-check before publication.
• Run just VERSION=vX.Y.Z release-github to create or update only the GitHub Release.
• Run just VERSION=vX.Y.Z release only when registry publication is intended.
• Run just VERSION=vX.Y.Z release-verify after publication to compare the tag target, GitHub Release target, crates.io, npm, PyPI, wrapper launch, Homebrew formula, and binary release assets.
• GitHub Releases require a signed annotated vX.Y.Z tag that GitHub reports as Verified.
• just release stops before dispatch when the requested version already exists on crates.io.
• crates.io publication requires the CARGO_REGISTRY_TOKEN GitHub secret.