기반·도구

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 또는 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

입력부터 출력까지

  1. content와 options 전달하기

    library에서는 Markdown 문자열과 LintOptions를 MarkdownLinter::lint에 전달하고, CLI에서는 kml check README.md나 --stdin 등으로 입력 source를 지정합니다. config와 rule 설정은 사용하는 실행 경로에 맞춰 해결됩니다.

  2. 모든 rule 평가하기

    linter는 options에서 severity map을 만들고 Markdown rule 그룹을 대상 path·content·rule 설정에 적용합니다. 결과는 공개 LintResult로 변환되어 사용 측이 rule ID와 severity를 읽을 수 있습니다.

  3. 진단 또는 수정 결과 다루기

    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 위반이 진단으로 나타나는 입력입니다.

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

통합 조건과 책임 경계

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차 판정으로 사용할 수 있습니다.

근거

조사 시점의 공개 저장소를 바탕으로 소개합니다. 링크된 고정 커밋에서 구현과 사용 방법을 확인할 수 있습니다.

저장소읽기 안내1e1da206977a
근거 · KML
모든 제품