01
已實作功能
02
開始使用
- 將 katana-markdown-model 加入 Rust 專案。
- 傳入 MarkdownInput,並將 parse 得到的文件模型交給後續處理。
cargo add katana-markdown-model請準備 Rust 與必要的開發工具,並在導入前透過連結的 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
使用情境
將 Markdown 傳遞到後續處理的常見 AST
當您想要將 Markdown 轉換為渲染器中立的 KmmDocument 和 KmmNode 並將相同的結構傳遞給檢視器、linter 和專有分析時,請使用它。標題、段落、連結、影像、公式、表格、程式碼塊、警報等都可以通過 KmmNodeKind 進行區分。
編輯後解析後設資料目標
當節點位置或 ID 在文件編輯期間發生更改時,將使用已儲存後設資料的 byte range、line/column、fingerprint 和前後 context 來解析新文件中的候選。您可以區分已解決、已移動、有衝突和未解決的結果,因此它可用於註釋和跟蹤外部資訊。
02 / KMM
從輸入到輸出的流程
建立 Markdown 輸入
將路徑和正文傳遞給 MarkdownInput::from_content。輸入可以是讀取的檔案或記憶體中的字串,使用者在解析之前決定如何處理源。
解析為Kmm文件
KatanaMarkdownModel::parse 返回 Result<KmmDocument, KmmError>。成功的文件有 path、fingerprint 和頂層 nodes,每個節點都有 kind、source 和 children。
使用 AST 或協調結果
通常,節點和 source span 會傳遞給 viewer/linter;更新後設資料時,將 old document、new document 和 metadata 傳給 reconcile。結果包括更新後的 metadata 和每個 target 的 resolution。
03 / KMM
主要 API 與 CLI
KatanaMarkdownModel::parse — Markdown解析- 這是解析 MarkdownInput 並返回 KmmDocument 的基本入口點。解析失敗會以 KmmError 的形式返回給呼叫者,因此輸入錯誤可以由使用者處理。
KmmNodeKind — 節點種類- 將結構化 Markdown 元素(如標題、段落、文本、連結、影像、InlineMath、DollarMathBlock、列表、程式碼塊、表格、Alert(警報)等)表示為 enum。後續無需 renderer-specific reparse 即可確定 kind。
MetadataTarget — 中繼資料目標- 將 file path、node ID、byte range、line-column range、text fingerprint 和 surrounding context 儲存為 metadata。它是 target resolution 的輸入,不僅依賴於單個行號。
TargetResolutionKind — 定位結果狀態- TargetResolutionKind 將目標結果分為 Resolved、Moved、Conflict 和 Unresolved。由於可以返回移動的節點、多個候選及原因,呼叫方可以選擇自動採用或人工確認。
04 / KMM
透過範例理解
讀取 AST 和源位置
解析 Markdown,包括標題和段落,讀取每個頂級節點的型別和源範圍。當您想要使用原始文本的位置資訊而不是繪圖結果將顯示選擇和分析結果連線到原始文本時,這是入口點。
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
整合條件與責任邊界
保持渲染器中立的邊界
KMM 提供與渲染器無關的文件模型,並且不依賴於特定的檢視器或編輯器實現。使用者不是將繪圖和 UI 同步引入 KMM,而是將 KMM AST 轉換為自己的職責。
假設KMM的初始範圍
source range、line-column、raw snippet、fingerprint 和 metadata target reconcile 都是可用的初始範圍。我們不直接引用 KDV 或 KatanA 實現,僅與 KMM 公開的 node 和 metadata API 整合。
依據
內容根據調查時點的公開儲存庫。可透過連結中的固定提交確認實作與使用方式。