Mise en forme du texte avec Markdown

Dans de nombreux champs de texte, le texte peut être structuré et mis en forme avec Markdown : avec des titres, des listes, des tableaux, des liens et des passages mis en évidence. Markdown s'écrit comme du texte ordinaire et est appliqué automatiquement à l'affichage.

Cette page montre la notation à gauche et le résultat à droite. Elle décrit exactement ce qui est pris en charge dans nos applications. De nombreux aperçus de Markdown sur Internet présentent des notations supplémentaires. Une partie d'entre elles ne fonctionne pas ici, voir Ce qui n'est pas pris en charge.

Mises en évidence

Ce que vous écrivez	Ce que cela donne
`gras`	gras
`italique`	italique
`*gras et italique*`	*gras et italique*
`~~barré~~`	~~barré~~
`largeur de caractère fixe`	`largeur de caractère fixe`

Paragraphes et sauts de ligne

Un simple saut de ligne (une pression sur Entrée) est affiché comme saut de ligne. Une ligne vide (deux pressions sur Entrée) commence un nouveau paragraphe avec un espacement un peu plus grand.

Ce que vous écrivez Ce que cela donne

Première ligne
Deuxième ligne

Première ligne
Deuxième ligne

Premier paragraphe

Deuxième paragraphe

Premier paragraphe

Deuxième paragraphe

Appuyer plusieurs fois sur Entrée n'aide pas

Trois lignes vides ou plus ont exactement le même effet qu'une seule. L'espacement ne peut donc pas être augmenté en appuyant plusieurs fois sur la touche Entrée.

Titres

Les titres commencent par un ou plusieurs dièses, suivis d'une espace. Il existe six niveaux.

Ce que vous écrivez	Ce que cela donne
`# Niveau 1`	Niveau 1
`## Niveau 2`	Niveau 2
`### Niveau 3`	Niveau 3
`#### Niveau 4`	Niveau 4
`###### Niveau 6`	Niveau 6

À partir du quatrième niveau, la taille de police reste identique à celle du texte courant. Les niveaux se distinguent alors par la graisse et la couleur.

Listes

Les énumérations commencent par un trait d'union, les listes numérotées par 1.. Les sous-entrées sont indentées.

Ce que vous écrivez	Ce que cela donne
`- Premier point - Deuxième point - Sous-entrée`	Premier point Deuxième point Sous-entrée
`1. Première étape 2. Deuxième étape 1. Étape intermédiaire`	Première étape Deuxième étape Étape intermédiaire

Dans les listes numérotées, la numérotation change à chaque niveau : chiffres, puis chiffres romains minuscules, puis lettres.

Quelle indentation ?

Une sous-entrée doit être indentée de la largeur du marqueur de liste de l'entrée parente, espace suivante comprise : avec -, cela fait deux espaces, avec 1. trois, et avec des numéros à deux chiffres comme 10. quatre. Si l'indentation est insuffisante, il n'y a pas de sous-niveau, mais une entrée supplémentaire au même niveau.

Listes de tâches

Ce que vous écrivez	Ce que cela donne
`- [x] fait - [ ] ouvert`	☑ fait ☐ ouvert

Les cases servent à l'affichage et ne peuvent pas être cochées. Le statut est géré dans le texte, c'est-à-dire en ajoutant ou en supprimant le x.

Liens et images

Ce que vous écrivez	Ce que cela donne
`[Byron Informatik](https://www.byron.ch)`	Byron Informatik
`https://www.byron.ch`	https://www.byron.ch
`![Plan d'étage](image.png)`

Une adresse écrite directement dans le texte devient elle aussi automatiquement un lien. Les images sont réduites à la largeur disponible.

Citations

Les citations commencent par un chevron fermant. Elles conviennent pour détacher des propos de tiers ou des extraits d'un message.

Ce que vous écrivez	Ce que cela donne
`> Retour du vendredi. > > Deuxième paragraphe dans la citation.`	Retour du vendredi. Deuxième paragraphe dans la citation.
`> Message du client. > > > Réponse du concierge.`	Message du client. Réponse du concierge.

Les citations peuvent être imbriquées en ajoutant un chevron supplémentaire devant. Cela convient pour représenter un échange, par exemple un message et la réponse correspondante. Chaque niveau est affiché un peu plus pâle ; au-delà de deux niveaux, la lecture devient donc difficile.

Tableaux

Les colonnes sont séparées par des barres verticales, la deuxième ligne sépare l'en-tête du contenu.

Ce que vous écrivez Ce que cela donne

| Appareil | Statut |
| -------- | ------ |
| BY-HE-01 | Erreur |
| BY-NE-02 | OK     |

Appareil	Statut
BY-HE-01	Erreur
BY-NE-02	OK

Les barres n'ont pas besoin d'être alignées les unes sous les autres, mais cela facilite la lecture dans le champ de saisie. Si un tableau est plus large que la place disponible, il peut être défilé latéralement.

Code et largeur de caractère fixe

Pour des expressions isolées dans le texte courant, des accents graves suffisent. Pour des passages de plusieurs lignes, on en utilise trois en guise d'encadrement. Si un langage suit les caractères d'ouverture, les mots-clés sont mis en couleur.

Ce que vous écrivez	Ce que cela donne
La valeur `3.14.2` est nouvelle.	La valeur `3.14.2` est nouvelle.
```sql SELECT Id FROM Reader; ```	`SELECT Id FROM Reader;`
``` C:\Temp\ablage ```	`C:\Temp\ablage`

Sans indication de langage, le passage reste sans couleur, mais conserve la largeur de caractère fixe. C'est le bon choix pour les chemins, les extraits de journal et tout ce dont les espaces doivent être conservés.

Ligne de séparation

Ce que vous écrivez	Ce que cela donne
`Texte avant --- Texte après`	Texte avant Texte après

Autres mises en forme avec HTML

Markdown ne connaît pas certaines mises en forme. Pour celles-ci, du HTML peut être écrit directement dans le texte.

Ce que vous écrivez	Ce que cela donne
`<kbd>Ctrl</kbd> + <kbd>C</kbd>`	`Ctrl` + `C`
`m<sup>2</sup>`	m²
`H<sub>2</sub>O`	H₂O
`<abbr title="Système de contrôle d'accès">SCA</abbr>`	SCA
`<details> <summary>Plus</summary> Contenu </details>`	Plus Contenu
`<mark>mis en évidence</mark>`	mis en évidence
`<span class="colorWarn">urgent</span>`	urgent

Le HTML est limité à un sous-ensemble sûr

Pour des raisons de sécurité, le HTML intégré est filtré. Sont autorisées les mises en forme citées ci-dessus ainsi que les liens, les tableaux et les images. Un balisage non autorisé disparaît, le texte qu'il contient est conservé. Sont en outre supprimées les mises en forme propres passant par l'attribut style. Une couleur inscrite en dur comme style="color: red" n'est donc pas reprise. Les scripts et les blocs de style (<script>, <style>) ne sont jamais exécutés, ils sont affichés comme du texte.

Chevrons dans le texte

Ce qui ressemble à une balise HTML est aussi lu comme telle. Un paramètre fictif comme <Identifiant> n'est pas du HTML connu et disparaît donc ; à sa place, il ne reste que l'espace entre les mots. Pour qu'il reste visible, écrivez une barre oblique inverse devant (\<Identifiant>) ou placez-le comme code entre deux accents graves. Ne sont pas concernés les signes de comparaison dans le texte courant (a < b) et les adresses entre chevrons comme <hans@byron.ch>.

Colorer le texte au moyen de classes

L'attribut class est conservé. Les classes de mise en forme de l'application concernée sont ainsi disponibles, par exemple colorWarn pour une couleur d'avertissement ou colorPrimary pour la couleur principale :

<span class="colorWarn">urgent</span>

Cela est préférable à une couleur inscrite en dur, car l'affichage suit le schéma de couleurs de l'application et reste lisible aussi bien en mode clair qu'en mode sombre. Les classes disponibles dépendent de l'application.

Dans les e-mails et dans le rapport PDF, les classes n'ont pas d'effet. Le texte y apparaît intégralement, mais sans couleur, car seuls quelques attributs sont repris par cette voie. Là où la mise en évidence doit également porter, le gras est la voie sûre.

Ce qui n'est pas pris en charge

Les aperçus Markdown courants listent sous « Extended Syntax » des notations qui ne sont pas mises en œuvre ici. La colonne du milieu montre ce qui apparaît à la place, celle de droite la voie qui mène au but ici.

Ce que vous écrivez	Ce que cela donne	Mieux ainsi
`==mis en évidence==`	==mis en évidence==	`<mark>mis en évidence</mark>` mis en évidence
`X^2^`	X^2^	`X<sup>2</sup>` X²
`H~2~O`	H2O	`H<sub>2</sub>O` H₂O
`Drôle :joy:`	Drôle :joy:	Insérer directement le caractère Drôle 😀
`Terme : Explication`	Terme : Explication	Terme en gras avec saut de ligne, ou un tableau Terme Explication
`Texte[^1] [^1]: La note de bas de page.`	Texte[^1] [^1]: La note de bas de page.	À la main, avec un chiffre en exposant et une ligne à la fin Texte¹
`### Titre {#id}`	Titre {#id}	Pas de remplacement, il n'y a pas de points d'ancrage ici