Documentation de plbls-markdown

plbls-markdown est une librairie ESM écrite en TypeScript qui convertit du contenu Markdown en HTML. Elle couvre la majorité des fonctionnalités du Markdown standard ainsi que plusieurs extensions avancées.

1. Fonctionnalités Supportées

La librairie prend en charge :

• Titres (Headings)
  Convertit les lignes commençant par un ou plusieurs # en balises <h1> à <h6>.

• Texte en Gras et Italique

  • Gras : Convertit **texte** ou __texte__ en <strong>texte</strong>.
  • Italique : Convertit *texte* ou _texte_ en <em>texte</em>.

• Texte Barré (Strikethrough)
  Convertit ~~texte~~ en <del>texte</del>.

• Code Inline et Blocs de Code

  • Code inline : Transforme du code entouré de backticks `code` en <code>code</code>.
  • Blocs de code : Convertit les blocs délimités par trois backticks en <pre><code> (avec option de spécifier la langue via une classe).

• Liens et Images

  • Liens : Transforme [texte](url "titre optionnel") en <a href="url" title="titre optionnel">texte</a>.
  • Images : Convertit ![texte alternatif](url) en <img src="url" alt="texte alternatif">.

• Blockquote
  Convertit les lignes débutant par > en balises <blockquote>.

• Listes (Ordonnées et Non Ordonnées)
  Prend en charge les listes à puces, numérotées et imbriquées, avec support pour les checkboxes (exemple : [x] ou [ ]).

• Règles Horizontales et Retours à la Ligne

  • Horizontal Rule : Convertit les lignes contenant uniquement ---, *** ou ___ en <hr>.
  • Line Break : Transforme les retours à la ligne forcés (par exemple deux espaces en fin de ligne) en <br>.

• Paragraphes
  Découpe le texte en paragraphes en enveloppant chaque bloc séparé par une ligne vide dans des balises <p>.

• Tables
  Convertit la syntaxe Markdown des tables (avec en-tête, ligne d’alignement et lignes de données) en <table>, avec <thead> et <tbody> et gère l’alignement des colonnes.

• Footnotes (Notes de Bas de Page)

  • Les définitions sous la forme [^id]: contenu sont extraites.
  • Les références [^id] dans le texte sont remplacées par des liens vers les notes.
  • Une section finale affiche toutes les notes sous forme d’une liste dans une balise <div class="footnotes">.

• Subscript et Superscript

  • Subscript : Convertit ~texte~ (en utilisant un tilde simple, pour éviter le conflit avec le strikethrough) en <sub>texte</sub>.
  • Superscript : Transforme ^texte^ en <sup>texte</sup>.

• Autolinks
  Convertit automatiquement les URL encadrées par des chevrons (ex. <http://example.com>) et les URL en texte brut en liens HTML. Le parser gère également les adresses email encadrées par des chevrons.

• Emojis
  Remplace les codes emoji du format :alias: par leur équivalent Unicode. Le mapping est construit dynamiquement en chargeant un fichier JSON (par exemple, emoji.json) qui contient la liste des emojis, leurs alias et autres informations.

2. Architecture et Structure du Code

La librairie est modulable et chaque fonctionnalité est encapsulée dans un fichier dédié situé dans le dossier parsers/. Par exemple :

• headings.parser.ts – Gestion des titres.
• bold.parser.ts, italic.parser.ts, strikethrough.parser.ts – Gestion du style du texte.
• inlineCode.parser.ts et codeBlock.parser.ts – Gestion du code.
• link.parser.ts et image.parser.ts – Gestion des liens et images.
• blockquote.parser.ts, list.parser.ts, horizontalRule.parser.ts, lineBreak.parser.ts, paragraph.parser.ts – Gestion des blocs et de la structure.
• table.parser.ts – Conversion des tables.
• footnotes.parser.ts – Traitement des notes de bas de page.
• subscript.parser.ts et superscript.parser.ts – Traitement des indices et exposants.
• autolink.parser.ts – Conversion automatique des URL.
• emoji.parser.ts – Conversion des codes emoji à partir du mapping JSON.

La fonction principale, parseMarkdown, orchestre l'exécution des différents parsers dans un ordre précis. Elle intègre également un mécanisme de protection et restauration des zones sensibles (blocs de code et code inline) pour éviter que leur contenu ne soit modifié par d'autres parsers.

3. Pipeline de Parsing

L’ordre d’exécution est crucial pour éviter les interférences entre les parsers. Par exemple, le mécanisme de protection des zones sensibles garantit que les blocs de code et le code inline ne subissent pas d’altérations lorsqu’ils sont traités par d’autres parsers (comme le bold, italic, etc.). Le pipeline typique est le suivant :

1. Protection des zones sensibles (code inline et blocs de code).
2. Application des parsers de structure et de style (titres, blockquote, listes, etc.).
3. Traitement des éléments spécifiques (tables, footnotes, subscript, superscript, autolinks, emojis).
4. Restauration des zones protégées.
5. Application finale des parsers pour le code (bloc et inline).

4. Utilisation

Pour utiliser la librairie, il suffit d'importer la fonction principale parseMarkdown et de lui fournir une chaîne de caractères contenant du Markdown. Des options (comme hardLineBreak) peuvent être passées pour adapter le comportement.

Exemple d’utilisation :

import { parseMarkdown } from 'plbls-markdown';

const markdownContent = `
# Bienvenue

Ceci est du **Markdown** avec des emojis :smile: et un lien <http://example.com>.

Voici une note[^1].

[^1]: C'est une note de bas de page.
`;

const htmlOutput = parseMarkdown(markdownContent, { hardLineBreak: true });
console.log(htmlOutput);

5. Extensibilité et Personnalisation

La structure modulaire permet d’ajouter ou de remplacer facilement des parsers. Tu peux :

• Désactiver certains parsers via des options.
• Ajouter des règles personnalisées.
• Étendre le mapping des emojis en modifiant le fichier JSON associé.

6. Compatibilité et Performances

• TypeScript & ESM : La librairie est développée en TypeScript et compilée en modules ESM, ce qui garantit une bonne intégration dans des environnements modernes (navigateur, Node.js, frameworks comme Angular, React, etc.).
• Légèreté : Aucun dépendance externe n’est requise pour le parsing, ce qui maintient un bundle léger.
• Tests : Chaque parser est testé individuellement, assurant une couverture complète et une maintenance facilitée.