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
どんな場面で使うか
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
入力から出力までの流れ
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- 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だけで統合します。
根拠
調査時点の公開リポジトリに基づく紹介です。リンク先の固定コミットで実装と手順を確認できます。