Parcourir la documentation
Le code et sa coloration
Des blocs de code lisibles, colorés à la publication et non chez le lecteur.
Le bloc de code s'insère avec /, ou en tapant trois accents graves en début de ligne.
La coloration est faite une fois, à la publication. Votre lecteur reçoit du HTML déjà coloré : aucun script ne tourne chez lui, et le code est lisible même s'il a coupé JavaScript.
Choisir un langage
Dix-neuf langages sont reconnus :
bash, css, diff, go, html, java, javascript, json, jsx, markdown, php, python, ruby, rust, sql, tsx, typescript, vue, yaml.
Les abréviations habituelles fonctionnent et sont traduites toutes seules : js, ts, py, rb, sh, shell, yml, md.
Un langage inconnu n'est pas une erreur : le bloc est rendu sans coloration, et rien n'est perdu.
Nommer un fichier
Le champ Nom du fichier — « app.ts » — affiche un onglet au-dessus du bloc. Il sert à situer le code quand un article en montre plusieurs.
Un bloc peut d'ailleurs en contenir plusieurs : « Ajouter un fichier » transforme le bloc en code à onglets, où le lecteur bascule de l'un à l'autre. C'est la bonne forme pour montrer un même exemple dans deux langages, ou un avant et un après.
Numéros de ligne et lignes surlignées
- Le réglage
- Ce qu'il fait
- Numéros de ligne
- Une case. Utile dès qu'on renvoie à « la ligne 12 »
- Lignes à souligner
- Un champ :
1,4-6
La syntaxe des lignes surlignées accepte des numéros et des intervalles, séparés par des virgules. Ce qui n'est pas reconnu est ignoré sans casser le bloc.
C'est le réglage le plus utile des deux : souligner les trois lignes qui changent dans un extrait de trente évite un paragraphe d'explication.
Le thème de coloration
Il se choisit pour tout le site, dans L'allure de votre site. Trois thèmes :
- Le thème
- L'allure
- GitHub
- Sobre, très lisible, familier
- Vitesse
- Contrasté, doux sur les yeux
- Catppuccin
- Pastel, chaleureux
Chacun existe en version claire et sombre, et suit le fond choisi par votre lecteur. Vous n'avez donc rien à décider pour le mode sombre : le bloc change avec la page.
Ce qui n'est pas fait
Pas d'exécution. Un bloc de code est du texte, jamais un terminal.
Pas de numérotation qui se copie. Les numéros de ligne sont affichés, mais ne partent pas dans le presse-papiers — copier un extrait donne le code, pas le code plus ses numéros.
Pas de repli automatique. Un bloc très large défile horizontalement plutôt que de couper les lignes au milieu d'un identifiant.