KatanA Markdown Linter

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.

See Markdown syntax support for the tested specification baseline, shared syntax boundaries, and safe-fix verification.

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.20.3 check README.md

npx --yes katana-markdown-linter@0.20.3 kml-mcp --workspace-root /absolute/path/to/workspace bunx --package katana-markdown-linter@0.20.3 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.20.3 kml check README.md

uvx --from katana-markdown-linter==0.20.3 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.20.3/kml-v0.20.3-aarch64-apple-darwin.tar.gz

curl -LO https://github.com/HiroyukiFuruno/katana-markdown-linter/releases/download/v0.20.3/kml-v0.20.3-aarch64-apple-darwin.tar.gz.sha256 shasum -a 256 -c kml-v0.20.3-aarch64-apple-darwin.tar.gz.sha256 tar -xzf kml-v0.20.3-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.

Formatting preserves blank lines and terminal newline counts inside fenced code and raw HTML blocks.

File and stdin formatting honor the resolved configuration for this layout subset, including explicit --config, rule enable flags, and settings such as MD007.indent. The same layout policy is used by editor formatting.

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 ; 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 --help print help without scanning files.

--locale and -l 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 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 `ava