Foundation / tool

KatanA Markdown Linter

A Rust library and kml CLI for Markdown linting, safe automated fixes, and formatting, with editor integration through LSP and an optional MCP server.

Developers and teams maintaining Markdown specifications and READMEs

01

Implemented capabilities

Detect Markdown lint violations

Evidence

Format with fmt and integrate with editors through LSP

Evidence

02

Getting started

  1. Install the CLI with Cargo and move to the project to inspect.
  2. Run kml check README.md to review diagnostics; use fix or fmt after reviewing the diff.

Prepare Rust and the required development tools, then check the linked README for environment requirements before installing. Examples show an entry point and do not guarantee operation in every environment.

Evidence
sh
cargo install katana-markdown-linter
kml check README.md
kml fix --diff README.md

01 / KML

Where it fits

Markdown quality gates in CI

Run kml check on a single file, a glob, stdin, or Markdown below the current directory and consume diagnostics with rule ID, severity, and position. A violation exits 1, while a filesystem or configuration error exits 2, so CI can classify the outcome.

Automated safe fixes and formatting

Use kml fix or check --fix to apply safe changes, and kml fmt to normalize line endings, blank lines, and list indentation. Unsafe fixes remain explicit opt-in, which lets CI and a developer's local rewrite use different responsibilities.

02 / KML

Input to output

  1. Provide content and options

    For the library, pass Markdown content and LintOptions to MarkdownLinter::lint; for the CLI, choose an input source such as kml check README.md or --stdin. Configuration and rule settings are resolved according to the selected execution path.

  2. Evaluate all rules

    The linter builds a severity map from the options, applies the Markdown rule set to the target path, content, and rule configuration, and converts the diagnostics into public LintResult values that expose rule IDs and severity.

  3. Handle diagnostics or fixes

    lint returns Vec<LintResult>, while fix applies fixable results to a copied string for at most 8 passes and returns FixResult. The CLI then communicates whether violations remain, including after fixing, through its exit code.

03 / KML

Key APIs and CLI

MarkdownLinter::lint
Lints in-memory content and returns Result<Vec<LintResult>, Error>, leaving file I/O to the caller. This makes it suitable for integration tests and editor connections that control how content is loaded.
MarkdownLinter::fix
Copies the input content and applies safe fixes until no fixable result remains or 8 passes have been attempted. The returned FixResult exposes the rewritten content, applied-fix count, and details so the caller can review the change.
MarkdownLinter::fix_with_results
Applies safe fixes to an already obtained LintResult slice. It is the low-level path for a caller that wants to display or inspect diagnostics first and then pass the same result set to rewriting.
kml check / fix / fmt
The CLI provides check, fix, and fmt commands with stdin, file, glob, and JSON-output paths. Callers can let the CLI discover files or keep content and LintOptions under direct library control.

04 / KML

Concrete example

Detect a heading-level violation

Pass Markdown containing # Title followed by ### Skipped heading to MarkdownLinter::lint and print each returned LintResult rule ID and message. This input mirrors the public crate test for a heading-increment violation, so the diagnostic is produced by the real rule path rather than by a hand-written result.

rust
use katana_markdown_linter::{LintOptions, MarkdownLinter};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let results = MarkdownLinter::lint(
        "# Title\n\n### Skipped heading\n",
        &LintOptions::default(),
    )?;
    for result in results {
        println!("{}: {}", result.rule_id, result.message);
    }
    Ok(())
}

05 / KML

Integration boundaries

Separate safe and unsafe responsibilities

Normal fix and check --fix stay on the safe-fix path, while unsafe fixes require explicit --unsafe --yes. Use the safe path in automated CI and reserve the explicitly confirmed unsafe path for an intentional developer rewrite.

Use exit codes as a quality gate

When no file is supplied, the CLI recursively scans Markdown below the current directory; a violation exits 1 and a filesystem or configuration error exits 2. CI can use those statuses as its primary gate without depending on diagnostic prose.

Evidence

This overview is based on the public repositories at the time of review. Verify implementation and usage in the linked pinned commits.

RepositoryREADME1e1da206977a
Evidence · KML
All products