Bibliothek

KatanA Markdown Model

Eine Rust-Bibliothek, die Markdown unabhängig vom Rendering in ein Dokumentmodell mit Knoten und Quellpositionen umwandelt.

Rust-Entwickler, die mit Markdown-Struktur, Knoten und Source-Spans arbeiten

01

Implementierte Fähigkeiten

Dokumentmodell aus Markdown-Eingaben erstellen

Belege

Quellpositionen über Knoten-IDs und Source-Spans erhalten

Belege

Externe Metadatenziele zwischen bearbeiteten Dokumenten abgleichen

Belege

02

Erste Schritte

  1. Fügen Sie katana-markdown-model zu einem Rust-Projekt hinzu.
  2. Übergeben Sie die Eingabe mit MarkdownInput und reichen Sie das geparste Dokumentmodell an die nächste Stufe weiter.
sh
cargo add katana-markdown-model

Bereiten Sie Rust und die erforderlichen Entwicklungstools vor und prüfen Sie vor der Installation die Umgebungsanforderungen im verknüpften README. Beispiele zeigen einen Einstieg und garantieren keinen Betrieb in jeder Umgebung.

Belege
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

Anwendungsfälle

Allgemeiner AST, der Markdown an die nachfolgende Verarbeitung weitergibt

Verwenden Sie es, wenn Sie Markdown in renderer-neutral KmmDocument und KmmNode konvertieren und dieselbe Struktur an Viewer, Linter und eigene Analysen übergeben möchten. Überschriften, Absätze, Links, Bilder, Formeln, Tabellen, Codeblöcke, Alerts usw. können mit KmmNodeKind unterschieden werden.

Metadatenziel nach der Bearbeitung auflösen

Wenn sich die Knotenposition oder ID während der Dokumentbearbeitung ändert, werden Kandidaten im neuen Dokument anhand von byte range, line/column, fingerprint und dem vorherigen/nächsten context der gespeicherten Metadaten aufgelöst. Sie können Resolved, Moved, Conflict und Unresolved unterscheiden und dies für Anmerkungen oder die Verfolgung externer Informationen verwenden.

02 / KMM

Ablauf von Eingabe zu Ausgabe

  1. MarkdownInput erstellen

    Übergeben Sie den Pfad und den Text an MarkdownInput::from_content. Die Eingabe kann eine gelesene Datei oder eine Zeichenfolge im Speicher sein, und der Benutzer entscheidet, wie er mit der Quelle vor dem Parsen umgeht.

  2. In KmmDocument analysieren

    KatanaMarkdownModel::parse gibt Result<KmmDocument, KmmError> zurück. Ein erfolgreiches Dokument verfügt über path, fingerprint und Top-Level-nodes, und jeder node verfügt über kind, source und children.

  3. Verwenden Sie AST oder gleichen Sie die Ergebnisse ab

    Normalerweise werden nodes und source spans an Viewer/Linter übergeben; bei einem Metadaten-Update werden old document, new document und metadata an reconcile übergeben. Das Ergebnis enthält aktualisierte metadata und die resolution jedes target.

03 / KMM

Wichtige APIs und CLI

KatanaMarkdownModel::parse — Markdown-Parser
Dies ist der grundlegende Einstiegspunkt, der MarkdownInput analysiert und KmmDocument zurückgibt. Analysefehler werden als KmmError an den Aufrufer zurückgegeben, sodass Eingabefehler vom Benutzer behandelt werden können.
KmmNodeKind — Knotentypen
Stellen Sie strukturierte Markdown-Elemente wie Heading, Paragraph, Text, Link, Image, InlineMath, DollarMathBlock, List, CodeBlock, Table und Alert als enum dar. Der nachgelagerte Verarbeitungsschritt kann kind ohne renderer-spezifisches erneutes Parsen bestimmen.
MetadataTarget — Metadaten-Ziele
Speichert file path, node ID, byte range, line-column range, text fingerprint und den umgebenden context als metadata. Es handelt sich um einen Reconcile-Eingang, der nicht nur auf einer einzelnen Zeilennummer basiert.
TargetResolutionKind — Auflösungszustände
Unterteilen Sie die Zielergebnisse in Resolved, Moved, Conflict und Unresolved. Da ein verschobener node, mehrere Kandidaten und der Grund zurückgegeben werden können, kann der Host zwischen automatischer Übernahme und manueller Bestätigung unterscheiden.

04 / KMM

An einem Beispiel verstehen

Lesen Sie AST und Quellposition

Analysiert Markdown, einschließlich Überschriften und Absätze, und liest den Typ und die Quellspanne für jeden Knoten der obersten Ebene. Dies ist der Einstiegspunkt, wenn Sie Anzeigeauswahlen und Analyseergebnisse mit dem Originaltext verbinden möchten, indem Sie die Positionsinformationen des Originaltextes und nicht das Zeichnungsergebnis verwenden.

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 und Grenzen

Renderer-neutralen Grenzbereich erhalten

KMM bietet ein renderer-neutrales Dokumentmodell und hängt nicht von einer bestimmten Viewer- oder Editor-Implementierung ab. Zeichnung und UI-Synchronisierung werden nicht in KMM integriert; der Host wandelt die KMM-AST in seine eigenen Verantwortlichkeiten um.

Unter der Annahme des anfänglichen Umfangs von KMM

source range, line-column, raw snippet, fingerprint und die erneute Auflösung von MetadataTarget gehören zum verfügbaren initialen Umfang. Die Integration referenziert KDV- oder KatanA-Implementierungen nicht direkt, sondern verwendet nur die von KMM veröffentlichten node- und metadata-APIs.

Belege

Diese Übersicht basiert auf den öffentlichen Repositories zum Zeitpunkt der Prüfung. Implementierung und Nutzung können in den verknüpften fixierten Commits geprüft werden.

Code-RepositoryREADME-Dokument9a7f647ab097
Belege · KMM
Alle Produkte