01
已实现功能
02
开始使用
- 通过 Cargo 安装 CLI,并进入要检查的项目。
- 执行 kml check README.md 查看问题;确认差异后再使用 fix 或 fmt。
请准备 Rust 和必要的开发工具,并在导入前通过链接的 README 确认环境要求。示例命令是功能入口,不保证在所有环境中运行。
依据cargo install katana-markdown-linter
kml check README.md
kml fix --diff README.md01 / KML
使用场景
使用 CI 检查 Markdown 质量
kml check 检查单个文件、glob、stdin 或当前目录下的 Markdown,并获取包含规则 ID、严重性和位置的诊断信息。发生违规时退出1,发生文件系统/配置错误时退出2,因此可以连接CI成功/失败判断。
自动安全修复和整形
使用 kml fix 或 check --fix 应用安全修复,并使用 kml fmt 安排换行符、空行和列表缩进等布局。不安全的修改可以仅限于明确的选择加入,从而将 CI 和开发人员的本地责任分开。
02 / KML
从输入到输出的流程
传递内容和选项
对于库,将 Markdown 字符串和 LintOptions 传递给 MarkdownLinter::lint,对于 CLI,使用 kml check README.md 或 --stdin 指定输入源。配置和规则设置根据使用的执行路径进行解析。
评估所有规则
linter 根据 options 创建 severity map,并将 Markdown rules 应用于 target path、content 和 rule settings。结果转换为公开的 LintResult,调用方可以读取 rule ID 和 severity。
处理诊断或纠正结果
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 测试的输入相同,会产生标题级别跳跃的诊断。
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不依赖于诊断文本的表示法,可以使用退出代码作为初步判断。
依据
内容基于调查时点的公开代码仓库。可通过链接中的固定提交确认实现和使用方法。