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
Conserver les positions source grâce aux identifiants de nœud et aux source spans
RéférencesRéconcilier les cibles de métadonnées externes entre des documents modifiés
Références02
Premiers pas
- Ajoutez katana-markdown-model à un projet Rust.
- Passez l'entrée avec MarkdownInput et transmettez le modèle analysé à l'étape suivante.
cargo add katana-markdown-modelPré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érencesuse 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
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.
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.
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.
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.