Prévisualiser du Markdown

Quel Markdown, et pourquoi le HTML est assaini

Le Markdown est une famille plutôt qu'une spécification unique, et le dialecte utilisé ici est l'ensemble largement admis du Markdown façon GitHub : titres, emphase, listes, liens, images, citations, tableaux, blocs de code délimités avec coloration syntaxique, listes de tâches, texte barré, notes de bas de page et liens automatiques. C'est ce que presque tout le monde écrit et ce que contient un README. Les dialectes plus exotiques et les plugins qu'ajoute tel ou tel site — blocs d'avertissement, shortcodes, templating — ne sont pas pris en charge : un document écrit pour un générateur précis peut donc afficher une partie de sa syntaxe telle quelle.

Le HTML brut est affiché, mais d'abord assaini, et c'est le point à bien comprendre. Le Markdown autorise volontairement le HTML, ce qui signifie qu'un fichier Markdown venu de n'importe où peut contenir une balise script, un gestionnaire d'événement en ligne, une iframe ou un lien javascript:. L'afficher tel quel exécuterait le code d'un inconnu dans votre session, simplement parce que vous avez collé son README pour le lire. Tout ce qui est exécutable est retiré avant tout affichage : la mise en forme survit, le code non.

C'est une leçon générale plutôt qu'un détail propre à cette page. Tout système qui affiche du Markdown fourni par les utilisateurs — une zone de commentaires, un wiki, un ticket d'assistance — affiche du HTML fourni par les utilisateurs, sauf s'il l'assainit, et « ce n'est que du Markdown » est la façon dont on passe à côté. Convertir le Markdown n'est pas une frontière de sécurité ; l'étape d'assainissement, si.

Vous obtenez un aperçu du contenu, pas d'un site en particulier. GitHub, GitLab et un générateur de documentation appliquent chacun leur propre feuille de style, leurs ancres de titres et leurs extensions, si bien que le même fichier s'affiche différemment dans chacun — la structure montrée ici est ce sur quoi ils s'accordent tous. Rien n'est récupéré par la page : les images référencées par une adresse web ne se chargent que si leur serveur l'autorise, et les chemins relatifs vers des fichiers d'un dépôt ne peuvent pas être résolus du tout.

Si vous cherchez autre chose

Pour un README que vous êtes en train d'écrire, prévisualisez-le là où il sera publié. L'éditeur de GitHub prévisualise avec son rendu exact, ses extensions et ses ancres, et la GitHub CLI — gh markdown-preview — le fait en local avec le même moteur de rendu. Pour de la documentation, le générateur lui-même (MkDocs, Docusaurus, Hugo) propose un aperçu à rechargement automatique qui montre le vrai style et la vraie navigation, c'est-à-dire ce que verra le lecteur.

Pour rédiger plutôt que vérifier, un éditeur Markdown avec un volet en direct — Obsidian, Typora, VS Code avec son aperçu intégré — vaut mieux que de coller dans une page à chaque fois, car l'aperçu se met à jour pendant la saisie et le fichier reste où il est. Cette page sert à lire le Markdown de quelqu'un d'autre, ou à jeter un coup d'œil rapide à quelque chose qu'on vous a envoyé.