函式庫

KatanA Markdown Model

將 Markdown 轉換為包含節點與原文位置的文件模型的 Rust 函式庫,可獨立於渲染處理文件結構。

處理 Markdown 結構、節點與 source span 的 Rust 開發者

01

已實作功能

從 Markdown 輸入建立文件模型

依據

透過節點 ID 與 source span 保留原文位置

依據

比對編輯前後文件中的外部中繼資料參照位置

依據

02

開始使用

  1. 將 katana-markdown-model 加入 Rust 專案。
  2. 傳入 MarkdownInput,並將 parse 得到的文件模型交給後續處理。
sh
cargo add katana-markdown-model

請準備 Rust 與必要的開發工具,並在導入前透過連結的 README 確認環境需求。執行範例是功能入口,不保證在所有環境中運作。

依據
rust
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

從輸入到輸出的流程

  1. 建立 Markdown 輸入

    將路徑和正文傳遞給 MarkdownInput::from_content。輸入可以是讀取的檔案或記憶體中的字串,使用者在解析之前決定如何處理源。

  2. 解析為Kmm文件

    KatanaMarkdownModel::parse 返回 Result<KmmDocument, KmmError>。成功的文件有 path、fingerprint 和頂層 nodes,每個節點都有 kind、source 和 children。

  3. 使用 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,包括標題和段落,讀取每個頂級節點的型別和源範圍。當您想要使用原始文本的位置資訊而不是繪圖結果將顯示選擇和分析結果連線到原始文本時,這是入口點。

rust
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 整合。

依據

內容根據調查時點的公開儲存庫。可透過連結中的固定提交確認實作與使用方式。

儲存庫閱讀指南9a7f647ab097
依據 · KMM
所有產品