Library
KatanA Markdown Model
A Rust library that converts Markdown into a document model with nodes and source positions, independent of rendering.
Rust developers working with Markdown structure, nodes, and source spans
01
Implemented capabilities
02
Getting started
- Add katana-markdown-model to a Rust project.
- Pass input with MarkdownInput and hand the parsed document model to the next stage.
cargo add katana-markdown-modelPrepare Rust and the required development tools, then check the linked README for environment requirements before installing. Examples show an entry point and do not guarantee operation in every environment.
Evidenceuse 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
Where it fits
A shared AST for downstream stages
Convert Markdown into renderer-neutral KmmDocument and KmmNode values for viewers, linters, or custom analysis. KmmNodeKind distinguishes headings, paragraphs, links, images, math, tables, code blocks, alerts, and other structures so downstream stages can share one AST.
Re-resolving metadata after edits
When editing moves nodes, saved metadata targets use their file path, node ID, byte and line-column ranges, text fingerprint, and surrounding context to resolve candidates in the new document. The result distinguishes resolved, moved, conflicted, and unresolved targets so annotations or external data can follow edits safely.
02 / KMM
Input to output
Create MarkdownInput
Pass a path and body to MarkdownInput::from_content. The body may have been read from a file or kept in memory, so the integrating caller decides how the source is obtained before parsing.
Parse a KmmDocument
KatanaMarkdownModel::parse returns Result<KmmDocument, KmmError>. On success the document contains its path, text fingerprint, and top-level nodes, while each KmmNode carries its kind, source span, and children; callers can therefore handle parse failures as KmmError.
Consume the AST or reconcile metadata
Usually pass nodes and source spans to a viewer or linter. When external metadata must follow an edit, pass the old document, new document, and metadata to reconcile; the result contains updated metadata together with each target's resolution outcome.
03 / KMM
Key APIs and CLI
KatanaMarkdownModel::parse- Parses MarkdownInput into KmmDocument and returns Result<KmmDocument, KmmError>, allowing callers to handle invalid input instead of receiving a partial document.
KmmNodeKind- Represents structured Markdown with enum variants including Heading, Paragraph, Text, Link, Image, InlineMath, DollarMathBlock, List, CodeBlock, Table, and Alert. Downstream code can inspect these kinds without reparsing for a particular renderer.
MetadataTarget- Stores a file path, node ID, byte range, line-column range, text fingerprint, and surrounding context as the input for metadata target resolution. This makes reconciliation depend on more than one line number.
TargetResolutionKind- Distinguishes Resolved, Moved, Conflict, and Unresolved outcomes. The result can include moved nodes, multiple candidates, and a reason, allowing callers to automate safe matches while routing ambiguous cases for human review.
04 / KMM
Concrete example
Read AST nodes and source spans
Parse Markdown containing a heading and paragraph with MarkdownInput::from_content, then inspect each top-level node's kind and source span rather than a rendered result. This is the smallest useful entry point when a viewer selection or analysis result must be tied back to original text; follow children for nested elements and pass old/new documents plus metadata to reconcile after edits.
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
Integration boundaries
Keep the renderer-neutral boundary
KMM provides a renderer-neutral document model and does not depend on a particular viewer or editor implementation. Rendering and UI synchronization stay with the integrating application, which converts the KMM AST into its own responsibilities.
Respect the initial scope
The initial public scope includes source ranges, line-column data, raw snippets, fingerprints, and metadata target reconciliation. Integrate through KMM's node and metadata APIs without taking KDV or KatanA implementation details as KMM dependencies.
Evidence
This overview is based on the public repositories at the time of review. Verify implementation and usage in the linked pinned commits.