Exemple – Markdown

Cet aide-mémoire, lui-même écrit en Markdown, montre comment appliquer des mises en forme à vos contenus en utilisant la syntaxe Markdown, reconnue pour sa simplicité.

Les développements qui suivent s’inspirent de : Syntaxe Markdown originale  (en français) ; Markdown simple  (en anglais) ; et Markdown Extra  (en français). Nous utilisons le Markdown Extra, plus récent et plus élaboré.

Lorsque plusieurs manières de faire sont possibles, nous allons systématiquement présenter celle qui est recommandée par le Guide des bonnes pratiques Markdown  de WordPress (en anglais).

Avis aux utilisateurs de synthèse vocale. Les textes qui suivent sont plus faciles à lire depuis une plage braille. Pour les parcourir en mode sonore, réglez le niveau des ponctuations à la plupart, et portez une attention particulière aux espaces.

Mises en forme fréquentes

Nous allons commencer par les mises en forme que vous allez utiliser le plus souvent, et finir par celles que vous n’utiliserez que rarement, voire jamais.

Paragraphe

Laissez une ligne vide entre chaque paragraphe, comme ceci :

Paragraphe 1.

Paragraphe 2.

Pour obtenir des lignes collées, ne laissez pas de lignes vides entre elles. Exemple :

CONSEIL CANADIEN DES AVEUGLES DE LONGUEUIL
1255, RUE BEAUREGARD, BUREAU 2509
LONGUEUIL QC  J4K 2M3

La présence ou l’absence d’espace entre les lignes est donc interprétée différemment. Nous verrons qu’il en est de même pour les espaces en début de ligne.

Titre

Mettez un ou plusieurs dièses consécutifs en début de ligne, suivi d’une espace, suivi du texte. Le nombre de # indique le niveau hiérarchique voulu, 1 étant le plus élevé. Le titre de votre page étant de niveau 1, vous devez commencer à subdiviser votre contenu avec des titres de niveau 2 ; puis, le cas échéant, subdiviser les sections de niveau 2 avec des titres de niveau 3, et ainsi de suite. Exemple de titre de niveau 2 :

## Ceci est un titre de niveau 2

Gras et italique

Entourez de deux astérisques le texte à mettre en gras, et d’un seul soulignement le texte à mettre en italique. Exemple :

Phrase avec du **gras** et de l'_italique_.

Pour combiner les 2 styles, disposez les * et _ en couches successives autour du texte, comme ceci :

Bout de texte _**gras et italique**_.

Exposant

Markdown Extra n’offrent malheureusement aucune syntaxe simplifiée pour mettre des caractères en exposant. Pour en avoir, vous devrez taper vous-même le code HTML approprié, comme dans l’exemple qui suit :

Le 1<sup>er</sup> janvier

Vous aurez compris qu’on peut sans problème injecter du HTML au sein d’un contenu balisé avec la syntaxe Markdown.

Lien

Mettez le texte entre crochets, immédiatement suivi de l’adresse électronique entre parenthèses, comme ceci :

[CCAL](https://ccalongueuil.org/)

Pour ajouter un texte qui s’affiche dans une info-bulle au survol du pointeur, faites suivre l’adresse électronique d’une espace, suivi du texte voulu entre guillemets, comme ceci :

[CCAL](https://ccalongueuil.org/ "Site Internet du CCAL").

Lorsque l’adresse électronique coïncide avec le texte que vous voulez voir apparaître comme lien, il suffit de mettre l’adresse électronique entre les signes < et >, comme ceci :

<https://ccalongueuil.org/>

Pour présenter l’adresse du lien sous forme de texte non cliquable, entourez l’adresse avec un accent grave au début et à la fin, comme ceci :

`https://ccalongueuil.org/`

Lorsque vous avez plusieurs liens dans un texte, vous pouvez utiliser un système de référence qui renvoie plus loin l’adresse électronique et l’éventuel texte à afficher sous forme d’info-bulle. Exemple :

Je reçoit 10 fois plus de trafic de [Google][1] que de
[Yahoo][2] ou [MSN][3].

  [1]: http://google.com/        "Google"
  [2]: http://search.yahoo.com/  "Yahoo Search"
  [3]: http://search.msn.com/    "MSN Search"

Ce qui rend le texte affiché en mode édition beaucoup plus facile à lire.

Liste

Nous montrerons comment créer des listes à puces et des listes numérotées. Chemin faisant, nous montrerons comment imbriquer une sous-liste à une liste.

Liste à puces

Tapez un trait d’union - en début de ligne suivi d’une espace pour chaque item, comme ceci :

- fraises
- pommes
- bananes

Pour imbriquer une sous-liste, indentez les éléments voulus avec des espaces, comme ceci :

* fraises
* pommes
  * vertes
  * rouges
* bananes

Liste numérotée

Tapez un chiffre en début de ligne suivi d’un point . suivi d’une espace devant chaque item, comme ceci :

1. Chapitre premier
2. Chapitre deuxième
3. Chapitre troisième

Pour imbriquer une sous-liste, indentez les éléments voulus avec des espaces, comme ceci :

1. Introduction
2. Développement
   1. Section A
   2. Section B
      1. Sous-section 1
      2. Sous-section 2
3. Conclusion

Tableau de données

Entourez le contenu de chaque cellule avec une barre verticale en la séparant du contenu avec au moins une espace, puis séparez la ligne d’en-tête des autres lignes avec des traits-d’union, comme ceci :

| En-tête 1    | En-tête 2    | En-tête 3    |
| ------------ | ------------ | ------------ |
| Cellule L1C1 | Cellule L1C2 | Cellule L1C3 |
| Cellule L2C1 | Cellule L2C2 | Cellule L2C3 |

On peut commencer ou finir une série de traits d’union par un deux-points pour indiquer l’alignement qu’on veut donner aux cellules de données.

Au besoin, mettez un deux-points à gauche pour un alignement à gauche, un deux-points à droite pour un alignement à droite, et un deux-points à gauche et à droite pour un alignement centré. Voici un tableau avec les 3 types d’alignements :

| Article   | Prix     | Quantité |
| :-------- | -------: | :------: |
| Casquette |   7,99 $ |    1     |
| Foulard   |  12,98 $ |    3     |

Notez que l’alignement à gauche est accessoire, puisqu’il s’agit de l’alignement par défaut.

Note de fin

Reproduisez le modèle suivant pour créer des notes et des appels de note au sein de votre document :

Paragraphe avec un appel de note[^1], puis un autre appel de note[^2].

[^1]: Texte de la première note.
[^2]: Texte de la deuxième note.

Les notes vont se retrouver sous forme de liste à la fin du document, et le balisage utilisé a spécifiquement été pensé pour être lisible et accessible aux outils d’adaptation en sonore.

Les chiffres utilisés pour numéroter les notes et les appels de note seront mis en exposant. L’appel de note deviendra un lien pointant vers la note qui lui correspond, et un lien de retour vers l’appel de note sera incorporé à la fin du texte de la note.

Veuillez à ce que le numéro d’une note ou d’un appel de note n’apparaisse pas 2 fois dans le même document.

Mises en forme plus rares

Bien qu’elles soient plus rarement utilisées, les mises en forme dont nous allons maintenant parler pourraient vous être utiles dans certaines circonstances.

Ligne séparatrice

Pour obtenir une ligne horizontale pleine largeur, tapez trois traits d’union consécutifs au début d’une ligne précédée d’une ligne vide, comme ceci :


---

Bloc de citation

Tapez le signe supérieur suivi d’une espace au début de chaque ligne de texte, incluant les lignes vides, comme ceci :

> Bloc de citation unique constitué 
> d'un premier paragraphe.
> 
> Suivi d'un deuxième
> paragraphe.

Pour inclure une citation dans une autre citation, utilisez deux signes supérieurs consécutifs, comme ceci :

> Bloc de citation principal
> 
>> Contenant un bloc 
>> de citation secondaire
> 
> Puis un paragraphe 
> final.

Notez qu’un bloc de citation peut contenir d’autres types de mises en forme Markdown telles que des titres, des listes, des liens, du gras, etc.

Abréviation

Lors de la première occurrence d’une abréviation dans une page, la meilleure pratique consiste à écrire l’expression au long suivi de son abréviation entre parenthèses, puis à utiliser l’abréviation uniquement, si on veut, les fois suivantes. Sinon, on peut aussi définir une abréviation accessible en la codifiant selon le modèle qui suit :

*[CCAL]: Conseil canadien des aveugles de Longueuil

Une fois ce code inscrit au début d’une ligne quelque part dans votre texte, toutes les occurrences de l’abréviation CCAL qui se trouvent avant ou après seront correctement codées en HTML. Ce qui vous permet de faciliter la maintenance en groupant vos abréviations où bon vous semble.

Liste de définitions

Tapez le mot à définir sur une ligne, suivi d’un deux-points au début de la ligne suivante, suivi d’au moins une espace, suivi de sa définition, puis laissez une ligne vide entre chaque paire, comme dans l’exemple suivant :

WordPress
:  Plateforme de publication en ligne

Markdown
:  Syntaxe de conversion du texte en HTML

Texte préformaté

Faites précéder chaque ligne d’une seule espace, comme ceci :

 U  n     T e x t e   préformaté
 e s t   reproduit  tel  q u e l.

Code en ligne

Entourez chaque bout de code en ligne avec un seul accent grave, comme suit :

La balise `<img>` doit avoir un attribut `alt`.

Bloc de code

Lorsque le code à présenter comporte plusieurs lignes, tapez trois accents graves consécutifs au début d’une ligne avant et après votre bloc de code, comme ceci :

```
body {
    background: #ffffff;
    color: #212121;
}
```

Caractères spéciaux

La plupart des signes de ponctuation peuvent acquérir une signification particulière en syntaxe Markdown. Continuez de les utiliser comme d’habitude, sans vous en préoccuper. Si le résultat obtenu ne correspond pas à celui auquel vous vous attendiez, il suffit de faire précéder le ou les signes suspects d’une barre oblique inverse. Cette barre sera absente du résultat final.

Voici la liste des caractères que vous pourriez avoir besoin de faire précéder d’une barre oblique inverse dans certaines circonstances particulières : : ! # * + - _ () [] {} | \.

Normand Lamoureux, M.A., SRDV
Expert en accessibilité du Web

Dernière mise à jour : 1 septembre 2020.