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
02
Getting started
- Install the CLI with Cargo and move to the project to inspect.
- 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.
Evidencecargo install katana-markdown-linter
kml check README.md
kml fix --diff README.md01 / 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
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.
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.
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.
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.