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 또는 current directory 아래의 Markdown을 검사하고 rule ID·severity·위치가 포함된 진단을 얻습니다. 위반이면 exit 1, filesystem/config error이면 exit 2이므로 CI의 성공 여부 판정에 연결할 수 있습니다.
safe fix와 포맷팅 자동화
kml fix 또는 check --fix로 safe한 수정를 적용하고 kml fmt로 줄바꿈·빈 줄·목록 들여쓰기 등의 레이아웃을 정리합니다. unsafe한 수정은 명시적인 opt-in으로 제한할 수 있어 CI와 개발자 로컬 작업의 책임을 나눌 수 있습니다.
02 / KML
입력부터 출력까지
content와 options 전달하기
library에서는 Markdown 문자열과 LintOptions를 MarkdownLinter::lint에 전달하고, CLI에서는 kml check README.md나 --stdin 등으로 입력 source를 지정합니다. config와 rule 설정은 사용하는 실행 경로에 맞춰 해결됩니다.
모든 rule 평가하기
linter는 options에서 severity map을 만들고 Markdown rule 그룹을 대상 path·content·rule 설정에 적용합니다. 결과는 공개 LintResult로 변환되어 사용 측이 rule ID와 severity를 읽을 수 있습니다.
진단 또는 수정 결과 다루기
lint는 Vec<LintResult>를 반환하고 fix는 최대 8 pass까지 수정 가능한 결과를 적용해 FixResult를 반환합니다. CLI는 위반이 남았는지, 수정 후에도 위반이 남았는지를 exit code로 CI에 전달합니다.
03 / KML
주요 API·CLI
MarkdownLinter::lint — 규칙 진단- 메모리의 content를 lint하고 Result<Vec<LintResult>, Error>를 반환합니다. 파일 I/O를 호출 측에서 제어하려는 통합 테스트나 editor 연동에 적합합니다.
MarkdownLinter::fix — safe 수정- content를 내부 복사하고 수정 가능한 진단이 없어지거나 8 pass에 도달할 때까지 safe fix를 적용합니다. 반환된 content, 적용 수, 상세 정보로 변경 결과를 확인할 수 있습니다.
MarkdownLinter::fix_with_results — 진단 기반 수정- 이미 얻은 LintResult에 safe fix를 적용하는 저수준 진입점입니다. 진단을 표시한 뒤 같은 결과를 수정 처리에 넘길 때 사용합니다.
kml check / fix / fmt — CLI 검사와 정리- CLI는 check, fix, fmt, stdin, file, glob, JSON 출력 등을 제공합니다. 사용자는 파일 탐색을 CLI에 맡기거나 library API에서 content와 options를 직접 관리할 수 있습니다.
04 / KML
구체적인 예
Rust API로 제목 수준 위반 검출하기
# Title 다음에 ### Skipped heading을 둔 Markdown을 MarkdownLinter::lint에 전달하고 반환된 각 LintResult의 rule ID와 message를 표시합니다. 공개 crate 테스트와 마찬가지로 제목 increment 위반이 진단으로 나타나는 입력입니다.
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
통합 조건과 책임 경계
safe/unsafe 책임 나누기
일반적인 fix와 check --fix는 safe fix로 제한하고 unsafe fix는 --unsafe --yes를 명시합니다. 자동 CI에서는 safe 경로를, 개발자가 의도적으로 다시 쓰는 경우에는 unsafe 경로를 사용하는 운영으로 나눌 수 있습니다.
exit code를 품질 gate에 연결하기
파일을 지정하지 않으면 current directory 아래를 재귀 처리하고 위반은 exit 1, filesystem/config error는 exit 2입니다. CI는 진단 본문의 표현에 의존하지 않고 exit code를 1차 판정으로 사용할 수 있습니다.
근거
조사 시점의 공개 저장소를 바탕으로 소개합니다. 링크된 고정 커밋에서 구현과 사용 방법을 확인할 수 있습니다.