库

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
全部产品