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.