基础设施与工具

KatanA Markdown Linter

提供 Markdown 规则检查、安全自动修正和格式化的 Rust 库与 kml CLI,也支持 LSP 编辑器连接和可选 MCP 服务器。

持续维护 Markdown 规格文档和 README 的开发者与团队

01

已实现功能

通过 Markdown lint 检测规则违规

依据

通过 fix 提供修正辅助

依据

通过 fmt 格式化并通过 LSP 连接编辑器

依据

02

开始使用

  1. 通过 Cargo 安装 CLI,并进入要检查的项目。
  2. 执行 kml check README.md 查看问题;确认差异后再使用 fix 或 fmt。

请准备 Rust 和必要的开发工具,并在导入前通过链接的 README 确认环境要求。示例命令是功能入口,不保证在所有环境中运行。

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

01 / KML

使用场景

使用 CI 检查 Markdown 质量

kml check 检查单个文件、glob、stdin 或当前目录下的 Markdown,并获取包含规则 ID、严重性和位置的诊断信息。发生违规时退出1,发生文件系统/配置错误时退出2,因此可以连接CI成功/失败判断。

自动安全修复和整形

使用 kml fix 或 check --fix 应用安全修复,并使用 kml fmt 安排换行符、空行和列表缩进等布局。不安全的修改可以仅限于明确的选择加入,从而将 CI 和开发人员的本地责任分开。

02 / KML

从输入到输出的流程

  1. 传递内容和选项

    对于库,将 Markdown 字符串和 LintOptions 传递给 MarkdownLinter::lint,对于 CLI,使用 kml check README.md 或 --stdin 指定输入源。配置和规则设置根据使用的执行路径进行解析。

  2. 评估所有规则

    linter 根据 options 创建 severity map,并将 Markdown rules 应用于 target path、content 和 rule settings。结果转换为公开的 LintResult,调用方可以读取 rule ID 和 severity。

  3. 处理诊断或纠正结果

    lint 返回 Vec<LintResult>,fix 应用最多 8 次可修复结果并返回 FixResult。在 CLI 中,退出代码用于通知 CI 违规是否仍然存在,或者即使在纠正后违规是否仍然存在。

03 / KML

主要 API 与 CLI

MarkdownLinter::lint — Markdown检查
MarkdownLinter::lint 对内存中的 content 执行检查并返回 Result<Vec<LintResult>, Error>。它适用于由调用方控制文件 I/O 的集成测试和 editor 集成。
MarkdownLinter::fix — 安全修复
MarkdownLinter::fix 复制 content 并应用 safe fix,直到没有可修复的诊断或达到 8 个 pass。您可以从返回值的 content、applied count 和 details 查看变更结果。
MarkdownLinter::fix_with_results — 修复已有诊断
一个低级入口点,用于对已获得的 LintResult 应用安全修复。用于显示诊断结果,然后将相同的结果传递给纠正过程。
kml check / fix / fmt — 命令行
CLI 提供检查、修复、fmt、stdin、文件、glob、JSON 输出等。用户可以将文件探索留给 CLI,或直接使用库 API 管理内容和选项。

04 / KML

通过示例理解

使用 Rust API 检测标题级别违规

把依次包含 # Title 和 ### Skipped heading 的 Markdown 传给 MarkdownLinter::lint,并打印每个 LintResult 的 rule ID 和 message。这与公开 crate 测试的输入相同,会产生标题级别跳跃的诊断。

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

集成条件与职责边界

独立的安全/不安全责任

常规修复和 check --fix 仅限于安全修复,不安全修复则通过 --unsafe --yes 明确指定。操作可分为自动CI中的安全路线和开发人员故意重写的情况下的不安全路线。

将退出代码连接到质量门

如果未指定文件,则将在当前目录下执行递归处理,对于违规将发出 exit 1,对于文件系统/配置错误将发出 exit 2。 CI不依赖于诊断文本的表示法,可以使用退出代码作为初步判断。

依据

内容基于调查时点的公开代码仓库。可通过链接中的固定提交确认实现和使用方法。

代码仓库阅读指南1e1da206977a
依据 · KML
全部产品