3 18 Markdown vers HTML

Eragon edited this page 2024-03-14 14:48:15 +01:00

Unescape Escape

Table of Contents

• Fonctionnement
• Extensions
• PC-links
• Conversion M↓ vers HTML
• Assainissement du HTML

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Quelques notes techniques concernant le filtre de conversion du Markdown vers HTML

Fonctionnement

Le filtre Jinja markdown (app/utils/filters/markdown.py) s'organise dans cet ordre :

1. Déclaration des extensions
   1. Extensions standards définies par leur nom
   2. Extensions standards définies par un constucteur avec paramètres
   3. Extensions personnalisées définies par un constructeur
2. Conversion du Markdown au format HTML
3. Assainissement du HTML pour éviter les injections de code

Notons que la sécurité ne repose pas sur la conversion du Markdown vers HTML mais bien par l'assainissement du HTML à postériori.

Extensions

La biliothèque Markdown qui est utilisée dans la v5 est fournie avec plusieurs extensions. Se référer à la documentation pour plus de détails. De nombreuses extensions tierces sont aussi disponibles.

Il est possible de créer des extensions personnalisées. Par convention, on les place dans app/utils/markdown_extensions.

Le processeur Markdown est assez complet, vous pouvez vous référer au code des extensions existantes et à la documentation de l'API pour créer de nouvelles extensions.

PC-links

Les PC-links sont des liens internes qui simplifient l'ajout de références aux objets du site (membres, etc.). Par exemple, [[u:Darks]] créé automatiquement un lien vers le profil de Darks.

La syntaxe d'un PC-link est [[<shortcut>:<content_id>]].

Pour ajouter de nouveaux PC-links, il faut :

1. Créer une fonction
   • Entrée
     • content_id: l'id tel que récupéré depuis le pattern
     • context: le bloc de texte dans lequel le lien a été trouvé
   • Sortie
     • une string (qui sera assainie par la suite)
     • ou un objet de type xml.etree.ElementTree
2. Ajouter cette fonction à la liste des handlers de la classe PCLinksInlineProcessor
   • Chaque clé du dictionnaire correspond à un shortcut
   • La fonction associée à la clé sera appelée avec les paramètres content_id et context

Conversion M↓ vers HTML

Rien de bien particulier, on appelle la fonction qui va bien avec la liste des extensions.

Assainissement du HTML

Il est globalement convenu que produire du HTML sain (donc dans injection de code) directement à partir de Markdown est une tâche quasi-impossible. Pour cela, on filtre le HTML produit avec Bleach, un outil dédié à cette tâche.

Bleach va par défaut tout échapper, et ne laissera passer que les balises et tags HTML autorisés. La configuration de ces derniers est définie dans app/utils/bleach_allowlist.py.

markdown_tags correspond à la liste des éléments HTML qui ne seront pas échappés. markdown_attrs correspond à la liste des tags autorisés par éléments. Tout ce qui ne rentre pas dans les exceptions listées sera echappé.

Lorsque vous ajoutez un nouveau module Markdown qui ajoute de nouvelles balises à la sortie, pensez à mettre à jour la liste des exceptions pour que votre convertisseur donne un résultat propre et non une bouillie de HTML echappé. La sécurité du site dépendant fortement de ce filtrage, attention à n'autoriser que ce qui est nécessaire et ne pose pas de problèmes de sécurité !