@kirigami/php-prepros 1.1.0 → 1.2.0

package/src/libraries/md.class.php

@@ -3,22 +3,22 @@
 class MD {
 
     // ========================================================================
-    // SYSTÈME DE PLUGINS
+    // PLUGIN SYSTEM
     //
-    // SYNTAXE INLINE (args sur la même ligne) :
-    //   {% nom_plugin arg1 arg2 "arg avec espaces" %}
+    // INLINE SYNTAX (args on the same line):
+    //   {% plugin_name arg1 arg2 "arg with spaces" %}
     //
-    // SYNTAXE BLOC (contenu multi-ligne) :
-    //   {% nom_plugin arg1 arg2
-    //   ligne de contenu 1
-    //   ligne de contenu 2
+    // BLOCK SYNTAX (multi-line content):
+    //   {% plugin_name arg1 arg2
+    //   content line 1
+    //   content line 2
     //   %}
     //
-    // Le callback reçoit toujours (array $args, string $body) :
-    //   - $args  : tableau des arguments passés sur la ligne d'ouverture
-    //   - $body  : contenu multi-ligne (vide "" pour les tags inline)
+    // The callback always receives (array $args, string $body):
+    //   - $args  : array of the arguments passed on the opening line
+    //   - $body  : multi-line content (empty "" for inline tags)
     //
-    // Exemples :
+    // Examples:
     //   GithubReadmeParser::registerPlugin('codepen', function(array $args, string $body): string {
     //       $id = htmlspecialchars($args[0] ?? '', ENT_QUOTES, 'UTF-8');
     //       return "<iframe src=\"https://codepen.io/embed/{$id}\"></iframe>";
@@ -38,25 +38,25 @@ class MD {
     private static array $plugins = [];
 
     /**
-     * Enregistre un plugin par son nom.
+     * Registers a plugin by name.
      *
-     * @param string   $name     Nom du tag, ex: "codepen"
+     * @param string   $name     Tag name, e.g. "codepen"
      * @param callable $callback function(array $args): string
-     *                           $args[0] = premier argument, $args[1] = second, etc.
+     *                           $args[0] = first argument, $args[1] = second, etc.
      */
     public static function registerPlugin(string $name, callable $callback): void {
         self::$plugins[strtolower(trim($name))] = $callback;
     }
 
     /**
-     * Supprime un plugin enregistré.
+     * Removes a registered plugin.
      */
     public static function unregisterPlugin(string $name): void {
         unset(self::$plugins[strtolower(trim($name))]);
     }
 
     /**
-     * Retourne la liste des plugins enregistrés.
+     * Returns the list of registered plugins.
      *
      * @return string[]
      */
@@ -65,7 +65,7 @@ class MD {
     }
 
     // ========================================================================
-    // Génère un id de type "slug" pour les ancres de titres (ATX et Setext).
+    // Generates a "slug"-style id for heading anchors (ATX and Setext).
     // ========================================================================
     private static function slugify(string $text): string {
         $id = strtolower(preg_replace('/[^\w\- ]/u', '', $text));
@@ -73,17 +73,16 @@ class MD {
     }
 
     // ========================================================================
-    // Convertit une largeur d'indentation (espaces/tabs) en nombre de colonnes,
-    // une tabulation comptant pour 4 espaces.
+    // Converts an indentation width (spaces/tabs) into a column count, a tab
+    // counting as 4 spaces.
     // ========================================================================
     private static function indentWidth(string $whitespace): int {
         return strlen(str_replace("\t", '    ', $whitespace));
     }
 
     /**
-     * Construit récursivement une liste (imbriquée) <ol>/<ul> à partir d'un
-     * tableau plat d'items { indent, type, text }. $i est avancé au fur et à
-     * mesure de la consommation des items.
+     * Recursively builds a (nested) <ol>/<ul> list from a flat array of items
+     * { indent, type, text }. $i is advanced as items are consumed.
      *
      * @param array<int, array{indent:int, type:string, text:string}> $items
      */
@@ -108,9 +107,9 @@ class MD {
     }
 
     // ========================================================================
-    // ÉMOJIS (syntaxe étendue) : :shortcode: → caractère unicode.
-    // Table non exhaustive mais couvrant les raccourcis les plus courants ;
-    // extensible via registerEmoji().
+    // EMOJIS (extended syntax): :shortcode: → unicode character.
+    // Non-exhaustive table but covering the most common shortcuts; extensible
+    // via registerEmoji().
     // ========================================================================
     /** @var array<string, string> */
     private static array $extraEmoji = [];
@@ -191,10 +190,145 @@ class MD {
         'speech_balloon' => '💬', 'thought_balloon' => '💭', 'zzz' => '💤', 'boom2' => '💥',
         'sos' => '🆘', 'new' => '🆕', 'ok' => '🆗', 'up' => '🆙', 'cool' => '🆒',
         'free' => '🆓', 'id' => '🆔', 'ng' => '🆖',
+
+        // -- Faces and emotions (continued) --------------------------------
+        'smiling_face_with_three_hearts' => '🥰', 'kissing' => '😗', 'kissing_closed_eyes' => '😚',
+        'kissing_smiling_eyes' => '😙', 'yum' => '😋', 'stuck_out_tongue' => '😛',
+        'stuck_out_tongue_winking_eye' => '😜', 'stuck_out_tongue_closed_eyes' => '😝',
+        'money_mouth_face' => '🤑', 'hugs' => '🤗', 'disappointed_relieved' => '😥',
+        'dizzy_face' => '😵', 'astonished' => '😲', 'open_mouth' => '😮', 'hushed' => '😯',
+        'fearful' => '😨', 'cold_sweat' => '😰', 'nauseated_face' => '🤢', 'vomiting_face' => '🤮',
+        'sneezing_face' => '🤧', 'face_with_thermometer' => '🤒', 'face_with_head_bandage' => '🤕',
+        'woozy_face' => '🥴', 'smiling_imp' => '😈', 'imp' => '👿', 'japanese_ogre' => '👹',
+        'japanese_goblin' => '👺', 'skull' => '💀', 'skull_and_crossbones' => '☠️',
+        'ghost' => '👻', 'alien' => '👽', 'space_invader' => '👾', 'robot' => '🤖',
+        'poop' => '💩', 'clown_face' => '🤡', 'smiley_cat' => '😺', 'smile_cat' => '😸',
+        'joy_cat' => '😹', 'heart_eyes_cat' => '😻', 'smirk_cat' => '😼', 'kissing_cat' => '😽',
+        'pouting_cat' => '😾', 'crying_cat_face' => '😿',
+
+        // -- Corps, gestes, personnages --------------------------------
+        'raised_hand' => '✋', 'raised_back_of_hand' => '🤚', 'vulcan_salute' => '🖖',
+        'pinching_hand' => '🤏', 'fist' => '✊', 'punch' => '👊', 'left_facing_fist' => '🤛',
+        'right_facing_fist' => '🤜', 'open_hands' => '👐', 'palms_up_together' => '🤲',
+        'nail_care' => '💅', 'selfie' => '🤳', 'ear' => '👂', 'nose' => '👃', 'brain' => '🧠',
+        'tongue' => '👅', 'lips' => '👄', 'tooth' => '🦷', 'bone' => '🦴',
+        'baby' => '👶', 'child' => '🧒', 'boy' => '👦', 'girl' => '👧', 'adult' => '🧑',
+        'man' => '👨', 'woman' => '👩', 'older_adult' => '🧓', 'older_man' => '👴', 'older_woman' => '👵',
+        'mage' => '🧙', 'superhero' => '🦸', 'supervillain' => '🦹', 'vampire' => '🧛',
+        'zombie' => '🧟', 'genie' => '🧞', 'merperson' => '🧜', 'elf' => '🧝', 'fairy' => '🧚',
+
+        // -- Animaux (suite) ---------------------------------------------
+        'wolf' => '🐺', 'boar' => '🐗', 'racehorse' => '🐎', 'zebra' => '🦓', 'deer' => '🦌',
+        'cow2' => '🐄', 'ox' => '🐂', 'water_buffalo' => '🐃', 'pig2' => '🐖', 'ram' => '🐏',
+        'sheep' => '🐑', 'goat' => '🐐', 'camel' => '🐫', 'dromedary_camel' => '🐪',
+        'llama' => '🦙', 'giraffe' => '🦒', 'elephant' => '🐘', 'rhinoceros' => '🦏',
+        'hippopotamus' => '🦛', 'mouse2' => '🐁', 'rat' => '🐀', 'hamster' => '🐹',
+        'chipmunk' => '🐿️', 'hedgehog' => '🦔', 'bat' => '🦇', 'duck' => '🦆', 'eagle' => '🦅',
+        'flamingo' => '🦩', 'peacock' => '🦚', 'parrot' => '🦜', 'swan' => '🦢',
+        'turkey' => '🦃', 'dove' => '🕊️', 'rooster' => '🐓', 'crocodile' => '🐊',
+        'turtle' => '🐢', 'lizard' => '🦎', 'snake' => '🐍', 'dragon_face' => '🐲',
+        'dragon' => '🐉', 'sauropod' => '🦕', 't-rex' => '🦖', 'whale2' => '🐋',
+        'shark' => '🦈', 'seal' => '🦭', 'squid' => '🦑', 'shrimp' => '🦐', 'lobster' => '🦞',
+        'crab' => '🦀', 'blowfish' => '🐡', 'tropical_fish' => '🐠', 'oyster' => '🦪',
+        'ant' => '🐜', 'spider' => '🕷️', 'spider_web' => '🕸️', 'scorpion' => '🦂',
+        'mosquito' => '🦟', 'microbe' => '🦠', 'paw_prints' => '🐾',
+
+        // -- Nature, plants, weather (continued) --------------------------------
+        'cherry_blossom' => '🌸', 'blossom' => '🌼', 'rose' => '🌹', 'wilted_flower' => '🥀',
+        'hibiscus' => '🌺', 'sunflower' => '🌻', 'tulip' => '🌷', 'herb' => '🌿',
+        'shamrock' => '☘️', 'fallen_leaf' => '🍂', 'leaves' => '🍃', 'mushroom' => '🍄',
+        'chestnut' => '🌰', 'crescent_moon' => '🌙', 'full_moon' => '🌕', 'new_moon' => '🌑',
+        'milky_way' => '🌌', 'stars' => '🌠', 'cyclone' => '🌀', 'fog' => '🌫️',
+        'wind_face' => '🌬️', 'tornado' => '🌪️', 'thunder_cloud_and_rain' => '⛈️',
+        'sweat_drops' => '💦', 'snowman' => '⛄', 'snowman_with_snow' => '☃️', 'comet' => '☄️',
+
+        // -- Nourriture (suite) --------------------------------------------
+        'tomato' => '🍅', 'eggplant' => '🍆', 'avocado' => '🥑', 'broccoli' => '🥦',
+        'carrot' => '🥕', 'corn' => '🌽', 'hot_pepper' => '🌶️', 'cucumber' => '🥒',
+        'potato' => '🥔', 'sweet_potato' => '🍠', 'peanuts' => '🥜', 'honey_pot' => '🍯',
+        'croissant' => '🥐', 'bagel' => '🥯', 'pretzel' => '🥨', 'pancakes' => '🥞',
+        'waffle' => '🧇', 'meat_on_bone' => '🍖', 'poultry_leg' => '🍗', 'bacon' => '🥓',
+        'sandwich' => '🥪', 'stuffed_flatbread' => '🥙', 'burrito' => '🌯', 'salad' => '🥗',
+        'shallow_pan_of_food' => '🥘', 'canned_food' => '🥫', 'bento' => '🍱',
+        'rice_ball' => '🍙', 'rice' => '🍚', 'curry' => '🍛', 'stew' => '🍲', 'oden' => '🍢',
+        'dango' => '🍡', 'shaved_ice' => '🍧', 'ice_cream' => '🍨', 'pie' => '🥧',
+        'cupcake' => '🧁', 'moon_cake' => '🥮', 'lollipop' => '🍭', 'custard' => '🍮',
+        'milk_glass' => '🥛', 'baby_bottle' => '🍼', 'mate' => '🧉', 'ice_cube' => '🧊',
+        'tumbler_glass' => '🥃', 'cup_with_straw' => '🥤', 'chopsticks' => '🥢',
+        'fork_and_knife' => '🍴', 'spoon' => '🥄', 'plate_with_cutlery' => '🍽️',
+
+        // -- Activities, sport, leisure --------------------------------------
+        'running' => '🏃', 'walking' => '🚶', 'swimming' => '🏊', 'surfing' => '🏄',
+        'skateboard' => '🛹', 'snowboarder' => '🏂', 'weight_lifting' => '🏋️',
+        'cyclist' => '🚴', 'medal_military' => '🎖️', 'ticket' => '🎫', 'circus_tent' => '🎪',
+        'performing_arts' => '🎭', 'art' => '🎨', 'clapper' => '🎬', 'microphone' => '🎤',
+        'headphones' => '🎧', 'musical_note' => '🎵', 'musical_score' => '🎼', 'guitar' => '🎸',
+        'violin' => '🎻', 'drum' => '🥁', 'trumpet' => '🎺', 'saxophone' => '🎷',
+        'musical_keyboard' => '🎹', 'chess_pawn' => '♟️', 'bowling' => '🎳',
+        'ice_skate' => '⛸️', 'ski' => '🎿', 'fishing_pole_and_fish' => '🎣',
+        'boxing_glove' => '🥊', 'martial_arts_uniform' => '🥋', 'goal_net' => '🥅',
+        'flying_disc' => '🥏', 'yo_yo' => '🪀', 'kite' => '🪁',
+
+        // -- Voyages et lieux (suite) ----------------------------------------
+        'airplane_departure' => '🛫', 'airplane_arriving' => '🛬', 'flying_saucer' => '🛸',
+        'motorcycle' => '🏍️', 'scooter' => '🛴', 'tractor' => '🚜', 'truck' => '🚚',
+        'articulated_lorry' => '🚛', 'trolleybus' => '🚎', 'minibus' => '🚐', 'metro' => '🚇',
+        'station' => '🚉', 'monorail' => '🚝', 'bullettrain_front' => '🚄',
+        'steam_locomotive' => '🚂', 'anchor' => '⚓', 'sailboat' => '⛵', 'canoe' => '🛶',
+        'speedboat' => '🚤', 'ferry' => '⛴️', 'passport_control' => '🛂', 'customs' => '🛃',
+        'baggage_claim' => '🛄', 'left_luggage' => '🛅', 'vertical_traffic_light' => '🚦',
+        'construction' => '🚧', 'fuelpump' => '⛽', 'busstop' => '🚏', 'moyai' => '🗿',
+        'statue_of_liberty' => '🗽', 'tokyo_tower' => '🗼', 'fountain' => '⛲',
+        'stadium' => '🏟️', 'ferris_wheel' => '🎡', 'roller_coaster' => '🎢',
+        'carousel_horse' => '🎠', 'beach_umbrella' => '🏖️', 'desert' => '🏜️',
+        'desert_island' => '🏝️', 'national_park' => '🏞️', 'sunrise' => '🌅',
+        'sunrise_over_mountains' => '🌄', 'sparkler' => '🎇', 'fireworks' => '🎆',
+        'city_sunset' => '🌇', 'bridge_at_night' => '🌉', 'houses' => '🏘️',
+        'derelict_house' => '🏚️', 'classical_building' => '🏛️', 'department_store' => '🏬',
+        'post_office' => '🏣', 'hotel' => '🏨', 'convenience_store' => '🏪', 'bank' => '🏦',
+        'factory' => '🏭',
+
+        // -- Objets (suite) ---------------------------------------------------
+        'watch' => '⌚', 'stopwatch' => '⏱️', 'timer_clock' => '⏲️', 'joystick' => '🕹️',
+        'floppy_disk' => '💾', 'cd' => '💿', 'dvd' => '📀', 'movie_camera' => '🎥',
+        'projector' => '📽️', 'telephone' => '☎️', 'pager' => '📟', 'fax' => '📠',
+        'candle' => '🕯️', 'fire_extinguisher' => '🧯', 'oil_drum' => '🛢️',
+        'money_with_wings' => '💸', 'credit_card' => '💳', 'yen' => '💴', 'euro' => '💶',
+        'pound' => '💷', 'briefcase' => '💼', 'balance_scale' => '⚖️', 'compass' => '🧭',
+        'triangular_ruler' => '📐', 'straight_ruler' => '📏', 'round_pushpin' => '📍',
+        'scissors' => '✂️', 'thread' => '🧵', 'yarn' => '🧶', 'safety_pin' => '🧷',
+        'basket' => '🧺', 'hourglass_flowing_sand' => '⏳', 'notebook' => '📓',
+        'notebook_with_decorative_cover' => '📔', 'page_facing_up' => '📄',
+        'page_with_curl' => '📃', 'bookmark_tabs' => '📑', 'bookmark' => '🔖',
+        'label' => '🏷️', 'receipt' => '🧾', 'card_index' => '📇', 'wastebasket' => '🗑️',
+        'old_key' => '🗝️', 'hammer_and_wrench' => '🛠️', 'pick' => '⛏️', 'shield' => '🛡️',
+        'syringe' => '💉', 'pill' => '💊', 'thermometer' => '🌡️', 'soap' => '🧼',
+        'broom' => '🧹',
+
+        // -- Symboles (suite) -----------------------------------------------
+        'heavy_multiplication_x' => '✖️', 'heavy_plus_sign' => '➕', 'heavy_minus_sign' => '➖',
+        'heavy_division_sign' => '➗', 'infinity' => '♾️', 'recycle' => '♻️', 'trident' => '🔱',
+        'atom_symbol' => '⚛️', 'om' => '🕉️', 'peace_symbol' => '☮️', 'yin_yang' => '☯️',
+        'wheel_of_dharma' => '☸️', 'star_of_david' => '✡️', 'star_and_crescent' => '☪️',
+        'cross' => '✝️', 'menorah' => '🕎', 'radioactive' => '☢️', 'biohazard' => '☣️',
+        'arrow_up' => '⬆️', 'arrow_down' => '⬇️', 'arrow_left' => '⬅️', 'arrow_right' => '➡️',
+        'arrow_upper_right' => '↗️', 'arrow_lower_right' => '↘️', 'arrow_lower_left' => '↙️',
+        'arrow_upper_left' => '↖️', 'arrows_clockwise' => '🔃', 'arrows_counterclockwise' => '🔄',
+        'back' => '🔙', 'end' => '🔚', 'on' => '🔛', 'soon' => '🔜', 'top' => '🔝',
+        'radio_button' => '🔘', 'red_circle' => '🔴', 'orange_circle' => '🟠',
+        'yellow_circle' => '🟡', 'green_circle' => '🟢', 'blue_circle' => '🔵',
+        'purple_circle' => '🟣', 'brown_circle' => '🟤', 'white_circle' => '⚪',
+        'black_circle' => '⚫',
+
+        // -- Drapeaux (suite) -------------------------------------------------
+        'triangular_flag_on_post' => '🚩', 'crossed_flags' => '🎌',
+        'us' => '🇺🇸', 'gb' => '🇬🇧', 'fr' => '🇫🇷', 'de' => '🇩🇪', 'es' => '🇪🇸',
+        'it' => '🇮🇹', 'jp' => '🇯🇵', 'cn' => '🇨🇳', 'kr' => '🇰🇷', 'ca' => '🇨🇦',
+        'au' => '🇦🇺', 'br' => '🇧🇷', 'in' => '🇮🇳', 'ru' => '🇷🇺', 'eu' => '🇪🇺',
     ];
 
     /**
-     * Enregistre (ou remplace) un raccourci emoji personnalisé.
+     * Registers (or replaces) a custom emoji shortcut.
      */
     public static function registerEmoji(string $shortcode, string $char): void {
         self::$extraEmoji[strtolower(trim($shortcode, ':'))] = $char;
@@ -206,12 +340,12 @@ class MD {
     }
 
     // ========================================================================
-    // LISTES DE DÉFINITION (syntaxe étendue)
-    //   Terme
-    //   : Définition
-    // Analyse procédurale ligne par ligne (plus sûre qu'une seule grosse
-    // regex pour regrouper plusieurs paires terme/définitions dans un même
-    // <dl>, séparées ou non par une ligne vide).
+    // DEFINITION LISTS (extended syntax)
+    //   Term
+    //   : Definition
+    // Procedural line-by-line analysis (safer than a single big regex for
+    // grouping several term/definition pairs into one <dl>, separated by a
+    // blank line or not).
     // ========================================================================
     private static function isDefinitionColonLine(string $line): bool {
         return (bool) preg_match('/^[ \t]*:[ \t]+.+$/', $line);
@@ -252,8 +386,8 @@ class MD {
                     $i++;
                 }
 
-                // Une seule ligne vide entre deux groupes reste dans le même <dl>
-                // si le groupe suivant est bien un nouveau terme.
+                // A single blank line between two groups stays in the same <dl>
+                // if the next group really is a new term.
                 if ($i < $n && trim($lines[$i]) === '') {
                     $j = $i;
                     while ($j < $n && trim($lines[$j]) === '') $j++;
@@ -275,35 +409,169 @@ class MD {
         return implode("\n", $out);
     }
 
+    // ========================================================================
+    // RAW HTML (safe subset, GitHub README style)
+    //
+    // Writing HTML tags directly (e.g. <div align="center">, <img>, <sub>,
+    // <br>, HTML tables...) is allowed ONLY if:
+    //   - the tag is part of the HTML_ALLOWED_TAGS whitelist;
+    //   - every attribute is part of the whitelist for that tag (or of the
+    //     global HTML_GLOBAL_ATTRS attributes);
+    //   - no attribute starts with "on" (onclick, onerror, ...);
+    //   - URLs (href/src) use a safe scheme (isSafeUrl).
+    //
+    // Any unknown or dangerous tag (script/style/iframe/...), or any
+    // non-whitelisted attribute, is silently stripped. The text content
+    // between the tags is NOT swallowed: it keeps being processed as normal
+    // markdown (that's what lets you have markdown headings, badges and images
+    // inside a <div align="center">...</div>).
+    // ========================================================================
+
+    private const HTML_ALLOWED_TAGS = [
+        'div', 'span', 'p', 'br', 'hr', 'wbr',
+        'b', 'strong', 'i', 'em', 'u', 's', 'strike', 'del', 'ins',
+        'mark', 'small', 'sub', 'sup', 'kbd', 'code', 'pre', 'abbr', 'q', 'cite',
+        'ul', 'ol', 'li', 'dl', 'dt', 'dd',
+        'table', 'thead', 'tbody', 'tfoot', 'tr', 'td', 'th', 'caption', 'colgroup', 'col',
+        'blockquote',
+        'a', 'img', 'picture', 'source', 'figure', 'figcaption',
+        'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+        'details', 'summary', 'center',
+    ];
+
+    /** Attributes allowed on any whitelisted tag. */
+    private const HTML_GLOBAL_ATTRS = ['id', 'class', 'title', 'align', 'valign', 'width', 'height', 'dir', 'lang'];
+
+    /** Extra attributes allowed, per tag. */
+    private const HTML_TAG_ATTRS = [
+        'a'       => ['href', 'name', 'target', 'rel'],
+        'img'     => ['src', 'alt', 'loading', 'srcset', 'sizes'],
+        'source'  => ['src', 'srcset', 'type', 'media'],
+        'td'      => ['colspan', 'rowspan'],
+        'th'      => ['colspan', 'rowspan', 'scope'],
+        'col'     => ['span'],
+        'ol'      => ['start', 'type'],
+        'details' => ['open'],
+    ];
+
+    /** Self-closing tags (no closing tag expected). */
+    private const HTML_VOID_TAGS = ['img', 'br', 'hr', 'wbr', 'source', 'col'];
+
+    /**
+     * Checks that a URL (href/src) uses a safe scheme: relative links, anchors,
+     * http(s), mailto, tel, or base64-encoded images (png/gif/jpeg/webp only —
+     * not svg+xml, which can embed a <script>).
+     * Notably rejects javascript:, vbscript:, data:text/html.
+     */
+    private static function isSafeUrl(string $url): bool {
+        $url = trim($url);
+        if ($url === '') return true;
+        // A path with no explicit scheme ("assets/x.png", "../x", "#anchor",
+        // "/x", "x") is a relative link or an anchor: always safe.
+        if (!preg_match('~^([a-zA-Z][a-zA-Z0-9+.\-]*):~', $url, $m)) return true;
+        $scheme = strtolower($m[1]);
+        if (in_array($scheme, ['http', 'https', 'mailto', 'tel'], true)) return true;
+        if ($scheme === 'data') {
+            // Base64-encoded images only — no data:image/svg+xml, which can
+            // embed a <script>, and no data:text/html.
+            return (bool) preg_match('~^data:image/(png|gif|jpe?g|webp);base64,~i', $url);
+        }
+        return false; // javascript:, vbscript:, file:, etc. → rejected
+    }
+
+    /**
+     * Sanitizes a single raw HTML tag (e.g. '<div align="center">', '</div>',
+     * '<img src="..." onerror="...">').
+     *
+     * @return string|null The cleaned tag to keep, an empty string to strip it
+     *                     silently, or null if it doesn't look like a valid
+     *                     HTML tag (in which case the caller strips it too, to
+     *                     be safe).
+     */
+    private static function sanitizeHtmlTag(string $tag): ?string {
+        if (!preg_match(
+            '/^<(\/)?([a-zA-Z][a-zA-Z0-9-]*)((?:\s+[a-zA-Z_:][a-zA-Z0-9_:.-]*(?:\s*=\s*(?:"[^"]*"|\'[^\']*\'|[^\s"\'>]+))?)*)\s*(\/)?>$/s',
+            $tag,
+            $m
+        )) {
+            return null;
+        }
+
+        $closing  = $m[1] === '/';
+        $tagName  = strtolower($m[2]);
+        $attrsRaw = $m[3];
+
+        if (!in_array($tagName, self::HTML_ALLOWED_TAGS, true)) {
+            return null;
+        }
+
+        if ($closing) {
+            return "</{$tagName}>";
+        }
+
+        $allowedAttrs = array_merge(self::HTML_GLOBAL_ATTRS, self::HTML_TAG_ATTRS[$tagName] ?? []);
+        $safeAttrs    = '';
+
+        if (preg_match_all(
+            '/([a-zA-Z_:][a-zA-Z0-9_:.-]*)(?:\s*=\s*("([^"]*)"|\'([^\']*)\'|([^\s"\'>]+)))?/',
+            $attrsRaw,
+            $am,
+            PREG_SET_ORDER
+        )) {
+            foreach ($am as $a) {
+                $attrName = strtolower($a[1]);
+                if ($attrName === '') continue;
+                if (str_starts_with($attrName, 'on')) continue; // safety net against JS handlers
+                if (!in_array($attrName, $allowedAttrs, true)) continue;
+
+                if ($tagName === 'details' && $attrName === 'open') {
+                    $safeAttrs .= ' open';
+                    continue;
+                }
+
+                $attrVal = $a[3] ?? ($a[4] ?? ($a[5] ?? ''));
+
+                if (in_array($attrName, ['href', 'src'], true) && !self::isSafeUrl($attrVal)) {
+                    continue;
+                }
+
+                $safeAttrs .= ' ' . $attrName . '="' . htmlspecialchars($attrVal, ENT_QUOTES, 'UTF-8') . '"';
+            }
+        }
+
+        $close = in_array($tagName, self::HTML_VOID_TAGS, true) ? ' /' : '';
+        return "<{$tagName}{$safeAttrs}{$close}>";
+    }
+
     // ========================================================================
 
     public static function toHtml(string $markdown): string {
 
         // ====================================================================
-        // ÉTAPE 1 : Normalisation des fins de ligne
+        // STEP 1: Line-ending normalization
         // ====================================================================
         $html = str_replace(["\r\n", "\r"], "\n", $markdown);
 
 
         // ====================================================================
-        // ÉTAPE 2 : PLUGINS
-        // Deux formes supportées :
+        // STEP 2: PLUGINS
+        // Two forms supported:
         //
-        //   INLINE : {% nom arg1 "arg 2" %}
+        //   INLINE: {% name arg1 "arg 2" %}
         //     → $args = ['arg1', 'arg 2'], $body = ''
         //
-        //   BLOC   : {% nom arg1\ncontenu\nsur\nplusieurs lignes\n%}
-        //     → $args = ['arg1'], $body = "contenu\nsur\nplusieurs lignes"
+        //   BLOCK : {% name arg1\ncontent\nover\nseveral lines\n%}
+        //     → $args = ['arg1'], $body = "content\nover\nseveral lines"
         //
-        // Les deux sont capturés par une seule regex qui distingue la présence
-        // d'un saut de ligne après les args (bloc) ou non (inline).
-        // Traités avant l'encodage XSS — réinjectés en toute dernière étape.
+        // Both are captured by a single regex that tells apart the presence of
+        // a newline after the args (block) or not (inline).
+        // Processed before XSS encoding — re-injected as the very last step.
         // ====================================================================
         $pluginBlocks = [];
 
         /**
-         * Parse une chaîne d'arguments en tableau.
-         * Supporte les mots simples, "guillemets doubles" et 'simples'.
+         * Parses an argument string into an array.
+         * Supports bare words, "double quotes" and 'single quotes'.
          */
         $parseArgs = static function (string $rawArgs): array {
             $args = [];
@@ -324,18 +592,18 @@ class MD {
         };
 
         $html = preg_replace_callback(
-            // Groupe 1 : nom du plugin
-            // Groupe 2 : args inline (tout ce qui est sur la première ligne après le nom)
-            // Groupe 3 : corps multi-ligne (présent seulement pour les tags blocs)
+            // Group 1: plugin name
+            // Group 2: inline args (everything on the first line after the name)
+            // Group 3: multi-line body (present only for block tags)
             '/\{%\s*([a-zA-Z0-9_-]+)([^\n%]*?)(?:\n([\s\S]*?))?\s*%\}/m',
             function ($matches) use (&$pluginBlocks, $parseArgs): string {
                 $name    = strtolower(trim($matches[1]));
                 $args    = $parseArgs(trim($matches[2] ?? ''));
-                // $matches[3] existe uniquement si le tag est multi-ligne
+                // $matches[3] exists only if the tag is multi-line
                 $body    = isset($matches[3]) ? trim($matches[3]) : '';
 
                 if (!isset(self::$plugins[$name])) {
-                    // Plugin inconnu : préservé encodé plutôt que silencieusement supprimé
+                    // Unknown plugin: kept encoded rather than silently removed
                     return htmlspecialchars($matches[0], ENT_QUOTES, 'UTF-8');
                 }
 
@@ -349,17 +617,17 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 2a : DÉFINITIONS DE NOTES DE BAS DE PAGE (footnotes)
-        //   [^1]: Texte de la note.
-        //   [^bignote]: Première ligne.
+        // STEP 2a: FOOTNOTE DEFINITIONS
+        //   [^1]: Note text.
+        //   [^bignote]: First line.
         //
-        //       Paragraphe suivant, indenté de 4 espaces ou 1 tabulation.
+        //       Following paragraph, indented by 4 spaces or 1 tab.
         //
-        //       `{ du code }`
-        // Extraites (et retirées du texte) AVANT les définitions de liens par
-        // référence, car [^label]: matcherait aussi leur regex sinon.
-        // Le contenu de chaque note est rendu via un appel récursif à
-        // toHtml() pour supporter plusieurs paragraphes, du code, etc.
+        //       `{ some code }`
+        // Extracted (and removed from the text) BEFORE reference link
+        // definitions, since [^label]: would otherwise match their regex too.
+        // Each note's content is rendered via a recursive call to toHtml() to
+        // support multiple paragraphs, code, etc.
         // ====================================================================
         $footnoteDefs = [];
         $html = preg_replace_callback(
@@ -381,12 +649,12 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 2b : DÉFINITIONS DE LIENS PAR RÉFÉRENCE
-        //   [label]: https://example.com "Titre optionnel"
-        //   [label]: <https://example.com> 'Titre optionnel'
-        //   [label]: https://example.com (Titre optionnel)
-        // Extraites (et retirées du texte) avant tout le reste ; utilisées
-        // plus loin par les liens [texte][label] / [texte][].
+        // STEP 2b: REFERENCE LINK DEFINITIONS
+        //   [label]: https://example.com "Optional title"
+        //   [label]: <https://example.com> 'Optional title'
+        //   [label]: https://example.com (Optional title)
+        // Extracted (and removed from the text) before everything else; used
+        // later by the [text][label] / [text][] links.
         // ====================================================================
         $refDefs = [];
         $html = preg_replace_callback(
@@ -402,7 +670,7 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 3 : BLOCS DE CODE (```lang ... ```)
+        // STEP 3: CODE BLOCKS (```lang ... ```)
         // ====================================================================
         $codeBlocks = [];
         $html = preg_replace_callback('/^```([a-zA-Z0-9_+-]*)\n([\s\S]*?)\n^```/m', function ($matches) use (&$codeBlocks) {
@@ -414,10 +682,10 @@ class MD {
         }, $html);
 
         // ====================================================================
-        // ÉTAPE 3a : BLOCS DE CODE INDENTÉS (4 espaces ou 1 tabulation)
-        // Reconnu seulement quand précédé d'une ligne vide (ou du début du
-        // document) et suivi d'une ligne vide (ou de la fin du document), afin
-        // d'éviter les conflits avec l'indentation des listes imbriquées.
+        // STEP 3a: INDENTED CODE BLOCKS (4 spaces or 1 tab)
+        // Recognized only when preceded by a blank line (or the start of the
+        // document) and followed by a blank line (or the end of the document),
+        // to avoid conflicts with the indentation of nested lists.
         // ====================================================================
         $html = preg_replace_callback(
             '/(?<=\n\n|^)((?:[ ]{4}|\t)[^\n]*(?:\n(?:[ ]{4}|\t)[^\n]*)*)(?=\n\n|\n*$)/',
@@ -434,13 +702,13 @@ class MD {
             $html
         );
 
-        // Code inline avec double backticks (permet d'inclure un backtick littéral)
+        // Inline code with double backticks (lets you include a literal backtick)
         $inlineCodes = [];
         $html = preg_replace_callback('/``(.+?)``/s', function ($matches) use (&$inlineCodes) {
             $content = $matches[1];
-            // Convention standard : si le contenu commence et finit par un
-            // espace (et n'est pas uniquement des espaces), on retire un
-            // espace de chaque côté — utile pour englober un ` en bordure.
+            // Standard convention: if the content starts and ends with a space
+            // (and isn't only spaces), strip one space on each side — handy for
+            // wrapping a ` at the edge.
             if (preg_match('/^ (.*[^ ]) $/s', $content, $trim)) {
                 $content = $trim[1];
             }
@@ -450,7 +718,7 @@ class MD {
             return $placeholder;
         }, $html);
 
-        // Code inline (`...`)
+        // Inline code (`...`)
         $html = preg_replace_callback('/`([^`\n]+)`/', function ($matches) use (&$inlineCodes) {
             $code        = htmlspecialchars($matches[1], ENT_QUOTES, 'UTF-8');
             $placeholder = "\x02IC" . count($inlineCodes) . "\x03";
@@ -460,10 +728,10 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 3b : ÉCHAPPEMENT DES CARACTÈRES (\* \_ \# etc.)
-        // Traité après l'extraction du code (le code reste littéral) et avant
-        // tout le reste, pour que \* n'ouvre pas une emphase, \# ne crée pas
-        // un titre, \- ne crée pas de liste, etc.
+        // STEP 3b: CHARACTER ESCAPING (\* \_ \# etc.)
+        // Processed after code extraction (code stays literal) and before
+        // everything else, so that \* doesn't open emphasis, \# doesn't create
+        // a heading, \- doesn't create a list, etc.
         // ====================================================================
         $escapes = [];
         $html = preg_replace_callback(
@@ -475,9 +743,9 @@ class MD {
             },
             $html
         );
-        // &#124; est la convention documentée (Markdown Extra / PHP Markdown)
-        // pour afficher un pipe littéral dans une cellule de tableau sans
-        // qu'il soit interprété comme séparateur de colonnes.
+        // &#124; is the documented convention (Markdown Extra / PHP Markdown)
+        // for showing a literal pipe in a table cell without it being
+        // interpreted as a column separator.
         $html = preg_replace_callback(
             '/&#124;/i',
             function () use (&$escapes): string {
@@ -490,9 +758,9 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 3d : LIENS AUTOMATIQUES <https://...> et <email@example.com>
-        // Traités avant l'encodage XSS car les caractères < > seraient encodés
-        // en &lt; &gt; et la regex ne matcherait plus.
+        // STEP 3d: AUTOMATIC LINKS <https://...> and <email@example.com>
+        // Processed before XSS encoding because the < > characters would be
+        // encoded to &lt; &gt; and the regex would no longer match.
         // ====================================================================
         $autolinks = [];
         $html = preg_replace_callback('/<(https?:\/\/[^\s<>]+)>/', function ($m) use (&$autolinks): string {
@@ -510,13 +778,13 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 3e : ALERTES GFM ET BLOCKQUOTES
-        // Traités avant l'encodage XSS car le caractère > serait encodé en &gt;
-        // et les regex ne matcheraient plus.
+        // STEP 3e: GFM ALERTS AND BLOCKQUOTES
+        // Processed before XSS encoding because the > character would be
+        // encoded to &gt; and the regexes would no longer match.
         // ====================================================================
         $blockquotes = [];
 
-        // Alertes GFM (> [!NOTE], etc.) — plus spécifique, traité en premier
+        // GFM alerts (> [!NOTE], etc.) — more specific, processed first
         $html = preg_replace_callback(
             '/^(>\s*\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\n(?:>[ \t]?[^\n]*\n?)*)/m',
             function ($matches) use (&$blockquotes): string {
@@ -529,38 +797,75 @@ class MD {
                 $blockquotes[$placeholder] = "<div class=\"markdown-alert markdown-alert-{$type}\">"
                     . "<p class=\"markdown-alert-title\">{$label}</p>"
                     . "<p>{$content}</p></div>";
-                // Le \n final consommé par la regex est réinjecté après le
-                // placeholder pour ne pas fusionner la ligne vide suivante
-                // avec celle du placeholder (ce qui fausserait par exemple
-                // la détection d'un titre Setext juste après).
+                // The trailing \n consumed by the regex is re-injected after
+                // the placeholder so the following blank line doesn't merge
+                // with the placeholder's line (which would break, for example,
+                // detecting a Setext heading right after).
                 return $placeholder . (str_ends_with($matches[1], "\n") ? "\n" : '');
             },
             $html
         );
 
-        // Blockquotes standards (imbrication gérée par récursion sur toHtml,
-        // qui ré-applique cette même règle sur le contenu déjà dé-préfixé
-        // d'un niveau de ">")
+        // Standard blockquotes (nesting handled by recursion through toHtml,
+        // which re-applies this same rule to the content already stripped of
+        // one ">" level)
         $html = preg_replace_callback('/^((?:>[ \t]?[^\n]*\n?)+)/m', function ($matches) use (&$blockquotes): string {
             $content = preg_replace('/^>[ \t]?/m', '', $matches[1]);
-            // Les deux espaces trailing sont laissés tels quels : toHtml() les gère lui-même
+            // The two trailing spaces are left as-is: toHtml() handles them itself
             $inner   = self::toHtml(trim($content));
             $placeholder = "\x02BQ" . count($blockquotes) . "\x03";
             $blockquotes[$placeholder] = "<blockquote>{$inner}</blockquote>";
-            // Voir commentaire ci-dessus : on préserve le \n final consommé.
+            // See the comment above: preserve the trailing \n that was consumed.
             return $placeholder . (str_ends_with($matches[1], "\n") ? "\n" : '');
         }, $html);
 
 
         // ====================================================================
-        // ÉTAPE 4 : Encodage XSS global
+        // STEP 3f: RAW HTML (safe subset, GitHub README style)
+        // Processed before XSS encoding because the < > characters would be
+        // encoded to &lt; &gt; and no longer recognized as tags.
+        // The content between the tags is not swallowed: it stays in the
+        // stream and keeps being processed as normal markdown.
+        // ====================================================================
+
+        // Intrinsically dangerous elements: removed along with their content
+        // (script/style/iframe can embed JS or load a third-party page;
+        // form/button/textarea/select/option have no place in markdown
+        // content).
+        $html = preg_replace(
+            '/<(script|style|iframe|object|embed|noscript|template|form|button|textarea|select|option)\b[^>]*>[\s\S]*?<\/\1>/i',
+            '',
+            $html
+        );
+
+        $rawHtml = [];
+        $html = preg_replace_callback(
+            '/<!--[\s\S]*?-->|<\/?[a-zA-Z][a-zA-Z0-9-]*(?:\s+[a-zA-Z_:][a-zA-Z0-9_:.-]*(?:\s*=\s*(?:"[^"]*"|\'[^\']*\'|[^\s"\'>]+))?)*\s*\/?>/',
+            function ($m) use (&$rawHtml): string {
+                $tag = $m[0];
+                // HTML comment: invisible, safe to remove.
+                if (str_starts_with($tag, '<!--')) return '';
+
+                $sanitized = self::sanitizeHtmlTag($tag);
+                if ($sanitized === null || $sanitized === '') return '';
+
+                $placeholder = "\x02HT" . count($rawHtml) . "\x03";
+                $rawHtml[$placeholder] = $sanitized;
+                return $placeholder;
+            },
+            $html
+        );
+
+
+        // ====================================================================
+        // STEP 4: Global XSS encoding
         // ====================================================================
         $html = htmlspecialchars($html, ENT_NOQUOTES, 'UTF-8');
 
 
         // ====================================================================
-        // ÉTAPE 5 : TABLEAUX GFM
-        // Supporte les lignes avec ou sans pipe final (| col | ou | col)
+        // STEP 5: GFM TABLES
+        // Supports rows with or without a trailing pipe (| col | or | col)
         // ====================================================================
         $html = preg_replace_callback(
             '/^(\|[^\n]+\|?\n)([ \t]*\|[ \t]*:?-+:?[ \t]*(?:\|[ \t]*:?-+:?[ \t]*)*\|?\n)((?:\|[^\n]+\|?\n?)+)/m',
@@ -608,26 +913,26 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 6 : (Alertes GFM et blockquotes traités à l'étape 3e)
+        // STEP 6: (GFM alerts and blockquotes handled in step 3e)
         // ====================================================================
 
 
         // ====================================================================
-        // ÉTAPE 7 : LISTES DE TÂCHES (GFM checkboxes)
+        // STEP 7: TASK LISTS (GFM checkboxes)
         // ====================================================================
         $html = preg_replace('/^[ \t]*[-*+] \[ \] (.+)$/m',    '<li class="task-item"><input type="checkbox" disabled /> $1</li>', $html);
         $html = preg_replace('/^[ \t]*[-*+] \[[xX]\] (.+)$/m', '<li class="task-item"><input type="checkbox" checked disabled /> $1</li>', $html);
 
 
         // ====================================================================
-        // ÉTAPE 7b : TITRES SETEXT (syntaxe alternative == / --)
-        //   Titre
+        // STEP 7b: SETEXT HEADINGS (alternative == / -- syntax)
+        //   Title
         //   =====   → <h1>
         //
-        //   Titre
+        //   Title
         //   -----   → <h2>
-        // Traité avant les titres ATX et avant les lignes séparatrices (une
-        // ligne de tirets juste après une ligne de texte est un titre, pas un <hr>).
+        // Processed before ATX headings and before horizontal rules (a line of
+        // dashes right after a line of text is a heading, not an <hr>).
         // ====================================================================
         $html = preg_replace_callback(
             '/^(?![ \t]*(?:#{1,6}[ \t]|>|```|\||[-*+][ \t]|\d+\.[ \t]))[ \t]*(\S.*?)[ \t]*(?:\{#([a-zA-Z0-9_\-:.]+)\}[ \t]*)?\n[ \t]*=+[ \t]*$/m',
@@ -650,7 +955,7 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 8 : TITRES (ATX : # à ######)
+        // STEP 8: HEADINGS (ATX: # to ######)
         // ====================================================================
         $html = preg_replace_callback(
             '/^(#{1,6})[ \t]+(.+?)[ \t]*(?:\{#([a-zA-Z0-9_\-:.]+)\}[ \t]*)?(?:[ \t]+#+)?$/m',
@@ -665,13 +970,13 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 9 : LISTES (puces et ordonnées, avec imbrication)
-        // Une seule passe détecte un bloc contigu de lignes qui sont soit une
-        // puce (-,*,+) soit un item numéroté, quel que soit leur niveau
-        // d'indentation ; le bloc est ensuite reconstruit récursivement en
-        // <ol>/<ul> imbriqués selon la profondeur d'indentation relative.
-        // Les items de tâches (déjà convertis en <li class="task-item">) ne
-        // matchent plus ce motif et ne sont donc pas ré-englobés ici.
+        // STEP 9: LISTS (bullets and ordered, with nesting)
+        // A single pass detects a contiguous block of lines that are either a
+        // bullet (-,*,+) or a numbered item, whatever their indentation level;
+        // the block is then rebuilt recursively into nested <ol>/<ul>
+        // according to the relative indentation depth.
+        // Task items (already converted to <li class="task-item">) no longer
+        // match this pattern and are therefore not re-wrapped here.
         // ====================================================================
         $html = preg_replace_callback(
             '/^([ \t]*(?:\d+\.|[-*+])[ \t]+.+(?:\n[ \t]*(?:\d+\.|[-*+])[ \t]+.+)*)/m',
@@ -686,7 +991,7 @@ class MD {
                     }
                 }
                 if (empty($items)) return $matches[1];
-                // Normalise le niveau d'indentation le plus bas à 0
+                // Normalize the lowest indentation level to 0
                 $minIndent = min(array_column($items, 'indent'));
                 foreach ($items as &$it) $it['indent'] -= $minIndent;
                 unset($it);
@@ -707,26 +1012,26 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 9b : LISTES DE DÉFINITION (syntaxe étendue)
-        //   Terme
-        //   : Définition
+        // STEP 9b: DEFINITION LISTS (extended syntax)
+        //   Term
+        //   : Definition
         // ====================================================================
         $html = self::extractDefinitionLists($html);
 
 
         // ====================================================================
-        // ÉTAPE 9c : RÉFÉRENCES DE NOTES DE BAS DE PAGE [^label]
-        // Converties AVANT l'emphase pour ne pas entrer en collision avec le
-        // nouvel exposant ^texte^ (un [^1] suivi plus loin d'un [^2] sur la
-        // même ligne pourrait sinon être interprété comme ^1] ... [^2^).
-        // La numérotation est séquentielle, dans l'ordre de première
-        // apparition dans le texte (comme documenté).
+        // STEP 9c: FOOTNOTE REFERENCES [^label]
+        // Converted BEFORE emphasis so they don't collide with the new
+        // superscript ^text^ (a [^1] followed later by a [^2] on the same line
+        // could otherwise be read as ^1] ... [^2^).
+        // Numbering is sequential, in order of first appearance in the text
+        // (as documented).
         // ====================================================================
         $footnoteOrder = [];
         $html = preg_replace_callback('/\[\^([^\]\s]+)\]/', function ($m) use (&$footnoteOrder, &$footnoteDefs): string {
             $label = strtolower(trim($m[1]));
             if (!isset($footnoteDefs[$label])) {
-                // Référence vers une note non définie : laissée telle quelle.
+                // Reference to an undefined note: left as-is.
                 return $m[0];
             }
             if (!isset($footnoteOrder[$label])) {
@@ -738,32 +1043,32 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 10 : TEXTE EN LIGNE (Gras, Italique, Barré, Surlignage,
-        // Indice/Exposant, Emoji)
+        // STEP 10: INLINE TEXT (Bold, Italic, Strikethrough, Highlight,
+        // Subscript/Superscript, Emoji)
         // ====================================================================
         $html = preg_replace('/\*\*\*(.+?)\*\*\*/s', '<strong><em>$1</em></strong>', $html);
         $html = preg_replace('/___(.+?)___/s',        '<strong><em>$1</em></strong>', $html);
         $html = preg_replace('/\*\*(.+?)\*\*/s',      '<strong>$1</strong>',          $html);
         $html = preg_replace('/__(.+?)__/s',           '<strong>$1</strong>',          $html);
         $html = preg_replace('/\*(.+?)\*/s',                          '<em>$1</em>',                  $html);
-        // Le _ italique ne doit matcher qu'aux frontières de mots pour ne pas
-        // capturer les snake_case, noms de packages (@php-wasm/node), etc.
+        // Italic _ must only match at word boundaries so it doesn't capture
+        // snake_case, package names (@php-wasm/node), etc.
         $html = preg_replace('/(?<!\w)_([^_\n]+)_(?!\w)/',           '<em>$1</em>',                  $html);
-        // Surlignage ==texte== (syntaxe étendue)
+        // Highlight ==text== (extended syntax)
         $html = preg_replace('/==(.+?)==/s',           '<mark>$1</mark>',              $html);
-        // Barré ~~texte~~ — traité AVANT le sous-script (simple ~) pour que
-        // celui-ci ne matche pas la moitié d'une paire de tildes doubles.
+        // Strikethrough ~~text~~ — processed BEFORE subscript (single ~) so the
+        // latter doesn't match half of a double-tilde pair.
         $html = preg_replace('/~~(.+?)~~/s',           '<del>$1</del>',                $html);
-        // Exposant ^texte^ (syntaxe étendue) — placé avant l'échappement des
-        // références de notes ([^label]) n'est pas un souci : celles-ci sont
-        // encadrées de crochets et ne forment donc pas de paire ^...^ isolée.
+        // Superscript ^text^ (extended syntax) — placing it before the note
+        // reference escaping ([^label]) is not a problem: those are wrapped in
+        // brackets and so don't form an isolated ^...^ pair.
         $html = preg_replace('/\^([^\^\n]+)\^/',       '<sup>$1</sup>',                $html);
-        // Sous-script ~texte~ (un seul tilde ; les ~~ ont déjà été consommés
-        // juste au-dessus par le barré).
+        // Subscript ~text~ (a single tilde; the ~~ were already consumed just
+        // above by strikethrough).
         $html = preg_replace('/~([^~\n]+)~/',          '<sub>$1</sub>',                $html);
 
-        // Émojis :shortcode: (syntaxe étendue) — les raccourcis inconnus sont
-        // laissés tels quels plutôt que silencieusement supprimés.
+        // Emojis :shortcode: (extended syntax) — unknown shortcuts are left
+        // as-is rather than silently removed.
         $html = preg_replace_callback('/:([a-zA-Z0-9_+\-]+):/', function ($m): string {
             $emoji = self::emojiFor($m[1]);
             return $emoji ?? $m[0];
@@ -771,9 +1076,9 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 11 : LIENS & IMAGES
-        // Les liens externes (https?://) reçoivent target="_blank" + rel="noopener noreferrer".
-        // Les liens internes (/page, #anchor, ../truc) n'en reçoivent pas.
+        // STEP 11: LINKS & IMAGES
+        // External links (https?://) get target="_blank" + rel="noopener noreferrer".
+        // Internal links (/page, #anchor, ../thing) don't.
         // ====================================================================
         $html = preg_replace(
             '/!\[([^\]]*)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/',
@@ -789,7 +1094,7 @@ class MD {
             return "<a href=\"{$href}\"{$titleAttr}{$extern}>{$text}</a>";
         };
 
-        // Liens par référence [texte][label] et [texte][] (raccourci = label = texte)
+        // Reference links [text][label] and [text][] (shortcut = label = text)
         $html = preg_replace_callback(
             '/\[([^\]]+)\]\[([^\]]*)\]/',
             function ($m) use (&$refDefs, $buildLink): string {
@@ -802,7 +1107,7 @@ class MD {
             $html
         );
 
-        // Liens markdown [texte](url "titre optionnel")
+        // Markdown links [text](url "optional title")
         $html = preg_replace_callback(
             '/\[([^\]]+)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/',
             function ($m) use ($buildLink): string {
@@ -811,9 +1116,9 @@ class MD {
             $html
         );
 
-        // URL nues https://... (syntaxe étendue : auto-link sans crochets).
-        // Exclut celles déjà entre guillemets/attributs (href="...") ou déjà
-        // transformées en lien pour ne pas les doubler.
+        // Bare URLs https://... (extended syntax: auto-link without brackets).
+        // Excludes those already inside quotes/attributes (href="...") or
+        // already turned into a link, so they don't get doubled.
         $html = preg_replace(
             '/(?<!["\'=>])\b(https?:\/\/[^\s<>"\')\]]+)/',
             '<a href="$1" target="_blank" rel="noopener noreferrer">$1</a>',
@@ -822,29 +1127,29 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 12 : LIGNES SÉPARATRICES
+        // STEP 12: HORIZONTAL RULES
         // ====================================================================
         $html = preg_replace('/^(?:[-*_][ \t]*){3,}$/m', '<hr />', $html);
 
 
         // ====================================================================
-        // ÉTAPE 13 : PARAGRAPHES
-        // Stratégie : on traite ligne par ligne. Les lignes qui commencent par
-        // une balise block-level ou un placeholder sont laissées telles quelles.
-        // Les lignes de texte brut consécutives sont accumulées puis wrappées
-        // dans un <p> quand on rencontre une ligne block ou une ligne vide.
+        // STEP 13: PARAGRAPHS
+        // Strategy: process line by line. Lines that start with a block-level
+        // tag or a placeholder are left as-is. Consecutive raw-text lines are
+        // accumulated then wrapped in a <p> when a block line or a blank line
+        // is reached.
         // ====================================================================
         $blockStartTags = ['<h', '<pre', '<ul', '<ol', '<li', '<table', '<thead', '<tbody',
                            '<tr', '<td', '<th', '<blockquote', '<div', '<hr', '<img',
                            '<dl', '<dt', '<dd',
-                           "\x02CB", "\x02PLG", "\x02BQ"];
+                           "\x02CB", "\x02PLG", "\x02BQ", "\x02HT"];
 
         $isBlockLine = static function (string $line) use ($blockStartTags): bool {
             $t = ltrim($line);
             if ($t === '') return false;
-            // Toute balise fermante (</...>) est toujours considérée comme une
-            // ligne "bloc" : ça évite qu'une fermeture de <table>, <thead>,
-            // <tr>, etc. finisse absorbée dans un <p> environnant.
+            // Any closing tag (</...>) is always treated as a "block" line:
+            // this keeps a closing </table>, </thead>, </tr>, etc. from being
+            // absorbed into a surrounding <p>.
             if (str_starts_with($t, '</')) return true;
             foreach ($blockStartTags as $tag) {
                 if (str_starts_with($t, $tag)) return true;
@@ -860,10 +1165,10 @@ class MD {
             if (empty($textBuffer)) return;
             $content = implode("\n", $textBuffer);
             if (trim($content) !== '') {
-                // Deux espaces en fin de ligne → <br> (convention markdown standard)
+                // Two trailing spaces → <br> (standard markdown convention)
                 $content = preg_replace('/  $/m', '<br>', $content);
-                // Saut de ligne simple → espace (comportement GitHub)
-                // Sauf si déjà converti en <br> ci-dessus
+                // Single line break → space (GitHub behavior)
+                // Unless already converted to <br> above
                 $content = preg_replace('/(?<!r>)\n/', ' ', $content);
                 $output[] = '<p>' . trim($content) . '</p>';
             }
@@ -875,7 +1180,7 @@ class MD {
                 $flushBuffer();
                 $output[] = $line;
             } elseif (trim($line) === '') {
-                // Ligne vide = séparateur de paragraphe
+                // Blank line = paragraph separator
                 $flushBuffer();
             } else {
                 $textBuffer[] = $line;
@@ -887,23 +1192,24 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 14 : Réinjecter les placeholders
+        // STEP 14: Re-inject the placeholders
         // ====================================================================
         $html = strtr($html, $pluginBlocks);
         $html = strtr($html, $blockquotes);
+        $html = strtr($html, $rawHtml);
         $html = strtr($html, $codeBlocks);
         $html = strtr($html, $inlineCodes);
         $html = strtr($html, $autolinks);
-        // Les échappements sont réinjectés en tout dernier, une fois que plus
-        // aucune regex Markdown ne peut les interpréter.
+        // The escapes are re-injected last, once no Markdown regex can
+        // interpret them anymore.
         $html = strtr($html, $escapes);
 
 
         // ====================================================================
-        // ÉTAPE 15 : BLOC DES NOTES DE BAS DE PAGE
-        // Ajouté en fin de document, uniquement si au moins une note a été
-        // référencée (les notes définies mais jamais référencées sont
-        // silencieusement ignorées).
+        // STEP 15: FOOTNOTES BLOCK
+        // Appended at the end of the document, only if at least one note was
+        // referenced (notes that are defined but never referenced are
+        // silently ignored).
         // ====================================================================
         if (!empty($footnoteOrder)) {
             $html .= "\n<div class=\"footnotes\">\n<ol>\n";