01
구현된 기능
02
시작하기
- Rust 프로젝트에 katana-markdown-model을 추가합니다.
- MarkdownInput으로 입력을 전달하고 parse 결과 문서 모델을 다음 처리 단계로 넘깁니다.
cargo add katana-markdown-modelRust와 필요한 개발 도구를 준비하고, 도입 전에 링크된 README에서 환경 요구 사항을 확인하세요. 실행 예시는 기능의 시작점이며 모든 환경에서의 동작을 보장하지 않습니다.
근거use katana_markdown_model::{KatanaMarkdownModel, MarkdownInput};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let document = KatanaMarkdownModel::parse(
MarkdownInput::from_content("README.md", "# Title\n\nBody\n"),
)?;
println!("{document:?}");
Ok(())
}01 / KMM
사용 장면
후속 처리에 넘기는 공통 AST
Markdown을 renderer-neutral한 KmmDocument와 KmmNode로 변환해 viewer, linter, 독자 분석에 같은 구조를 전달하려는 경우에 사용합니다. 제목, 단락, 링크, 이미지, 수식, 표, code block, alert 등을 KmmNodeKind로 구분할 수 있습니다.
편집 후 metadata target 재해결
문서 편집으로 node 위치나 ID가 바뀌었을 때 저장된 metadata의 byte range·line/column·fingerprint·앞뒤 context를 사용해 새 문서의 후보를 해결합니다. 해결, 이동, 충돌, 미해결을 결과로 구분할 수 있어 주석이나 외부 정보의 추적에 사용할 수 있습니다.
02 / KMM
입력부터 출력까지
MarkdownInput 만들기
path와 본문을 MarkdownInput::from_content에 전달합니다. 입력은 파일을 읽어도 되고 메모리의 문자열이어도 되며, parse 전에 사용 측이 source 취급 방식을 정합니다.
KmmDocument로 parse하기
KatanaMarkdownModel::parse는 Result<KmmDocument, KmmError>를 반환합니다. 성공한 document는 path, fingerprint, 최상위 nodes를 가지며 각 node는 kind, source, children을 가집니다.
AST 또는 reconcile 결과 사용하기
일반적으로 nodes와 source span을 viewer/linter에 전달하고 metadata 갱신에서는 old document·new document·metadata를 reconcile에 전달합니다. 결과에는 갱신된 metadata와 각 target의 resolution이 포함됩니다.
03 / KMM
주요 API·CLI
KatanaMarkdownModel::parse — 문서 모델 분석- MarkdownInput을 분석해 KmmDocument를 반환하는 기본 진입점입니다. parse 실패는 KmmError로 호출자에게 반환되므로 사용 측에서 입력 오류를 다룰 수 있습니다.
KmmNodeKind — Markdown 노드 종류- Heading, Paragraph, Text, Link, Image, InlineMath, DollarMathBlock, List, CodeBlock, Table, Alert 등 구조화된 Markdown 요소를 enum으로 나타냅니다. 후속 단계는 renderer 고유의 재parse 없이 kind를 판별할 수 있습니다.
MetadataTarget — 메타데이터 대상- metadata의 대상인 file path, node ID, byte range, line-column range, text fingerprint, 앞뒤 context를 보유합니다. 단일 행 번호에만 의존하지 않는 재해결 입력입니다.
TargetResolutionKind — 대상 해결 결과- target 결과를 Resolved, Moved, Conflict, Unresolved로 나눕니다. 이동한 node나 여러 후보, 이유를 반환할 수 있어 사용 측이 자동 채택과 사람 확인을 분기할 수 있습니다.
04 / KMM
구체적인 예
AST와 원문 위치 읽기
제목과 단락을 포함한 Markdown을 분석하고 최상위 각 노드의 종류와 source span을 읽습니다. 렌더링 결과가 아니라 원문의 위치 정보를 사용해 화면의 선택이나 분석 결과를 원래 텍스트에 연결하려 할 때의 진입점입니다.
use katana_markdown_model::{KatanaMarkdownModel, MarkdownInput};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let document = KatanaMarkdownModel::parse(MarkdownInput::from_content(
"README.md",
"# Title\n\nBody\n",
))?;
for node in &document.nodes {
println!("kind={:?} source={:?}", node.kind, node.source);
}
Ok(())
}05 / KMM
통합 조건과 책임 경계
renderer-neutral 경계 유지하기
KMM은 renderer-neutral 문서 모델을 제공하며 특정 viewer나 editor 구현에 의존하지 않습니다. 렌더링이나 UI 동기화를 KMM에 넣지 않고 사용 측이 KMM AST를 자신의 책임으로 변환합니다.
KMM의 초기 범위를 전제로 하기
source range, line-column, raw snippet, fingerprint, metadata target 재해결이 이용 가능한 초기 범위입니다. KDV나 KatanA 구현을 직접 참조하지 않고 KMM이 공개하는 node와 metadata API만으로 통합합니다.
근거
조사 시점의 공개 저장소를 바탕으로 소개합니다. 링크된 고정 커밋에서 구현과 사용 방법을 확인할 수 있습니다.