ライブラリ

KatanA Markdown Model

Markdownをノードと原文位置を持つ文書モデルへ変換するRustライブラリです。描画から独立して文書構造を扱えます。

Markdownの構造、ノード、source spanを扱うRust開発者

01

実装済みの機能

Markdown入力から文書モデルを構築

根拠

ノードIDとsource spanによる原文位置の保持

根拠

編集前後の文書間で外部メタデータの参照先を照合

根拠

02

はじめ方

  1. Rustプロジェクトにkatana-markdown-modelを追加します。
  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をrenderer-neutralなKmmDocumentとKmmNodeへ変換し、viewer、linter、独自解析へ同じ構造を渡したい場合に使います。見出し、段落、リンク、画像、数式、表、code block、alertなどをKmmNodeKindで区別できます。

編集後のmetadata target再解決

文書編集でnode位置やIDが動いたとき、保存済みmetadataのbyte range・line/column・fingerprint・前後contextを使って新文書の候補を解決します。解決、移動、競合、未解決を結果として区別できるため、注釈や外部情報の追従に使えます。

02 / KMM

入力から出力までの流れ

  1. MarkdownInputを作る

    pathと本文をMarkdownInput::from_contentへ渡します。入力はファイル読込でもメモリ上の文字列でもよく、parse前に利用側でsourceの扱いを決めます。

  2. KmmDocumentへparseする

    KatanaMarkdownModel::parseがResult<KmmDocument, KmmError>を返します。成功したdocumentはpath、fingerprint、トップレベルnodesを持ち、各nodeはkind、source、childrenを持ちます。

  3. 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
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を読み取ります。描画結果ではなく、原文の位置情報を使って表示上の選択や解析結果を元のテキストへ結び付けたいときの入口です。

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

組み込み条件と責務の境界

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だけで統合します。

根拠

調査時点の公開リポジトリに基づく紹介です。リンク先の固定コミットで実装と手順を確認できます。

リポジトリREADME9a7f647ab097
根拠 · KMM
すべての製品