Bibliothèque

KatanA Markdown Model

Une bibliothèque Rust qui convertit Markdown en modèle de document avec nœuds et positions source, indépendamment du rendu.

Développeurs Rust qui travaillent avec la structure Markdown, les nœuds et les source spans

01

Capacités implémentées

Construire un modèle de document à partir d'une entrée Markdown

Références

Conserver les positions source grâce aux identifiants de nœud et aux source spans

Références

Réconcilier les cibles de métadonnées externes entre des documents modifiés

Références

02

Premiers pas

  1. Ajoutez katana-markdown-model à un projet Rust.
  2. Passez l'entrée avec MarkdownInput et transmettez le modèle analysé à l'étape suivante.
sh
cargo add katana-markdown-model

Préparez Rust et les outils de développement nécessaires, puis consultez le README lié pour les prérequis avant l'installation. Les exemples indiquent un point de départ et ne garantissent pas le fonctionnement dans tous les environnements.

Références
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

Cas d'utilisation

Un AST commun pour les étapes suivantes

Convertissez Markdown en KmmDocument et KmmNode renderer-neutral pour le viewer, le linter ou une analyse spécifique. KmmNodeKind distingue titres, paragraphes, liens, images, formules, tableaux, blocs de code, alertes et autres structures afin que les étapes partagent le même AST.

Réconcilier les cibles après une édition

Quand l'édition déplace des nœuds, les métadonnées enregistrées utilisent chemin, node ID, plages d'octets et de lignes/colonnes, fingerprint et contexte voisin pour rechercher les candidats dans le nouveau document. Le résultat distingue Resolved, Moved, Conflict et Unresolved, afin de suivre annotations et données externes en sécurité.

02 / KMM

Flux entrée-sortie

  1. Créer MarkdownInput

    Passez le path et le contenu à MarkdownInput::from_content. Le contenu peut venir d'un fichier ou rester en mémoire ; l'appelant décide donc de la source avant le parse.

  2. Parser un KmmDocument

    KatanaMarkdownModel::parse renvoie Result<KmmDocument, KmmError>. En cas de succès, le document contient path, fingerprint et nodes de premier niveau ; chaque node possède kind, source et children.

  3. Utiliser l'AST ou le résultat de reconcile

    Passez habituellement nodes et source span au viewer ou au linter. Pour suivre des métadonnées après édition, donnez old document, new document et metadata à reconcile ; le résultat contient les métadonnées mises à jour et la résolution de chaque target.

03 / KMM

API et CLI principales

KatanaMarkdownModel::parse — Analyse de Markdown
Parse MarkdownInput en KmmDocument et renvoie Result<KmmDocument, KmmError>, afin que l'appelant traite une entrée invalide au lieu de recevoir un document partiel.
KmmNodeKind — Types de nœuds
Représente par enum les éléments Markdown structurés : Heading, Paragraph, Text, Link, Image, InlineMath, DollarMathBlock, List, CodeBlock, Table et Alert. L'étape suivante inspecte kind sans reparser pour un renderer particulier.
MetadataTarget — Cibles des métadonnées
Conserve file path, node ID, byte range, line-column range, text fingerprint et contexte voisin comme données d'entrée de la résolution. La réconciliation ne dépend ainsi pas d'un seul numéro de ligne.
TargetResolutionKind — États de résolution
Sépare les résultats Resolved, Moved, Conflict et Unresolved. Le résultat peut fournir un nœud déplacé, plusieurs candidats et une raison, pour automatiser les correspondances sûres et faire vérifier les cas ambigus.

04 / KMM

Comprendre par un exemple

Lire l'AST et les positions de la source

Le code parse un Markdown contenant un titre et un paragraphe, puis parcourt les nœuds de premier niveau pour lire leur type et leur source span. Il produit un modèle de document, pas du HTML ni une vue ; ces positions servent à relier une sélection ou une analyse au texte original.

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

Intégration et limites

Garder la frontière renderer-neutral

KMM fournit un modèle documentaire renderer-neutral sans dépendre d'un viewer ou d'un editor particulier. Le rendu et la synchronisation UI restent à l'application, qui transforme l'AST KMM selon ses propres responsabilités.

Respecter le périmètre initial

Le périmètre initial expose source range, line-column, raw snippet, fingerprint et la résolution des metadata targets. Intégrez-vous par les API node et metadata de KMM, sans prendre KDV ou KatanA comme dépendances d'implémentation.

Références

Cette présentation repose sur les dépôts publics au moment de l'examen. Vérifiez l'implémentation et l'utilisation dans les commits figés liés.

DépôtFichier README9a7f647ab097
Références · KMM
Tous les produits