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

Build a document model from Markdown input

Evidence

Preserve source positions through node IDs and source spans

Evidence

Reconcile external metadata targets between edited documents

Evidence

02

Getting started

  1. Add katana-markdown-model to a Rust project.
  2. Pass input with MarkdownInput and hand the parsed document model to the next stage.
sh
cargo add katana-markdown-model

Prepare 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.

Evidence
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

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

  1. 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.

  2. 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.

  3. 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.

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

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.

RepositoryREADME9a7f647ab097
Evidence · KMM
All products