Markdown

Hugo rend le Markdown avec Goldmark, un analyseur rapide et bien entretenu qui respecte la spécification CommonMark et reste compatible avec GitHub Flavored Markdown (GFM). Tout ce qui figure sur cette page s’affiche ici; les constructions signalées comme peu courantes peuvent ne pas survivre dans d’autres applications Markdown.

Mise en forme de base#

Gras et italique#

On ajoute de l’emphase en mettant le texte en **gras**, en _italique_ ou ***les deux***.

Les applications Markdown ne s’entendent pas sur le traitement des tirets bas au milieu d’un mot. Pour la compatibilité, utilisez des astérisques pour l’emphase en milieu de mot — *unfrigging***believable**, A*cat*meow — afin que l’emphase s’affiche correctement partout.

Ce site active aussi l’extension extras de Goldmark pour le ~~texte barré~~, le ++texte inséré++, le ==texte surligné== et l’exposant (1^st^). L’indice n’est pas activé; utilisez plutôt la balise HTML, comme dans H<sub>2</sub>O.

Le surlignage, l’indice et l’exposant sont peu courants ailleurs — testez-les dans l’application cible avant de vous y fier, et notez que certaines applications interprètent une paire de tildes simples (~x~) comme du texte barré plutôt que comme un indice. Les balises HTML <mark>, <sub> et <sup> restent la solution de repli portable.

Code#

Pour marquer un mot ou une phrase comme du code, entourez-le d’accents graves. S’il contient lui-même un ou plusieurs accents graves, échappez-le en l’entourant d’accents graves doubles:

Pour créer un bloc de code, indentez chaque ligne du bloc d’au moins quatre espaces ou d’une tabulation — ou mieux, utilisez un bloc de code délimité: aucune indentation nécessaire, et un identifiant de langage active la coloration syntaxique.

Lignes horizontales#

Utilisez trois astérisques (***), tirets (---) ou tirets bas (___) ou plus, seuls sur une ligne, avec une ligne vide avant et après. Sans la ligne vide, le --- transforme plutôt le texte au-dessus en titre.

Substitutions typographiques#

L’extension typographer, activée par défaut, remplace certaines combinaisons de caractères par des entités HTML:

Titres#

Pour créer un titre, ajoutez des carrés (#) devant un mot ou une phrase. Le nombre de carrés correspond au niveau du titre: trois carrés produisent un titre de niveau trois (<h3>).

Syntaxe alternative#

Sur la ligne sous le texte, ajoutez un nombre quelconque de caractères == pour un titre de niveau 1 ou de caractères -- pour un titre de niveau 2:

Heading level 1
===============

Heading level 2
---------------

Bonnes pratiques pour les titres#

Les applications Markdown ne s’entendent pas sur le traitement d’une espace manquante entre les carrés et le texte du titre. Pour la compatibilité, mettez toujours une espace entre les deux, et laissez une ligne vide avant et après un titre.

Identifiants de titre#

Beaucoup de processeurs Markdown acceptent des identifiants personnalisés pour les titres — certains en ajoutent automatiquement. Un identifiant personnalisé permet de pointer directement vers un titre et de le cibler en CSS. Pour en ajouter un, placez l’identifiant entre accolades sur la même ligne que le titre:

### My Great Heading {#custom-id}

Le HTML ressemble à ceci:

<h3 id="custom-id">My Great Heading</h3>

On pointe vers un titre doté d’un identifiant personnalisé en créant un lien standard dont l’URL est un carré (#) suivi de l’identifiant — ce qu’on appelle un lien d’ancrage:

[My Great Heading](#custom-id)

D’autres sites peuvent pointer vers le titre en ajoutant l’identifiant personnalisé à l’URL complète de la page, par exemple [Heading IDs](https://www.markdownguide.org/extended-syntax#heading-ids).

Liens#

Pour créer un lien, placez le texte du lien entre crochets et faites-le suivre immédiatement de l’URL entre parenthèses:

My favorite search engine is [Duck Duck Go](https://duckduckgo.com).

Titre de lien#

On peut ajouter un titre à un lien, qui s’affiche en infobulle quand la personne survole le lien. Placez-le entre guillemets droits après l’URL:

[Duck Duck Go](https://duckduckgo.com "The best search engine for privacy")

URL et adresses courriel#

Pour transformer rapidement une URL ou une adresse courriel en lien, placez-la entre chevrons:

<https://www.markdownguide.org>
<fake@example.com>

Beaucoup de processeurs Markdown transforment aussi automatiquement les URL nues en liens, même sans crochets. Pour empêcher une URL d’être liée, marquez-la comme du code avec des accents graves: `http://www.example.com`.

Mise en forme des liens#

Pour mettre un lien en évidence, ajoutez des astérisques avant et après les crochets et les parenthèses. Pour marquer un lien comme du code, ajoutez des accents graves à l’intérieur des crochets:

I love supporting the **[EFF](https://eff.org)**.
This is the _[Markdown Guide](https://www.markdownguide.org)_.
See the section on [`code`](#code).

Liens par référence#

Les liens par référence gardent les longues URL hors du paragraphe, ce qui rend le texte brut plus facile à lire. Ils ont deux parties: une partie en ligne et une définition rangée ailleurs dans le fichier.

La partie en ligne utilise deux paires de crochets. La première entoure le texte à lier; la seconde contient une étiquette qui pointe vers la définition. Une espace entre les deux paires est permise, et l’étiquette n’est pas sensible à la casse — elle peut contenir des lettres, des chiffres, des espaces ou de la ponctuation:

[hobbit-hole][1]

La définition est l’étiquette entre crochets, suivie immédiatement d’un deux-points et d’au moins une espace, puis de l’URL (au besoin entre chevrons), puis d’un titre facultatif entre guillemets doubles, guillemets simples ou parenthèses:

[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle "Hobbit lifestyles"

La définition peut se trouver n’importe où dans le document — juste après le paragraphe qui l’utilise, ou regroupée à la fin comme des notes. Le rendu est identique à celui d’un lien en ligne:

In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends
of worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to
eat: it was a [hobbit-hole][1], and that means comfort.

[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle "Hobbit lifestyles"

Bonnes pratiques pour les liens#

Les applications Markdown ne s’entendent pas sur le traitement des espaces au milieu d’une URL. Pour la compatibilité, encodez les espaces avec %20. Les parenthèses au milieu d’une URL posent aussi problème; encodez la parenthèse ouvrante avec %28 et la fermante avec %29. Autrement, utilisez la balise HTML <a>.

Liens internes sur ce site#

Ne tapez jamais une URL interne à la main. Utilisez relref, qui résout le chemin de contenu à la compilation et fait échouer la construction sur un mauvais chemin — voir Shortcodes. Pour choisir comment renvoyer vers des pages liées, voir Renvois.

Tableaux#

Le Markdown lui-même ne prend pas en charge les tableaux; il s’appuie sur les éléments HTML de tableau, sauf si le processeur implémente un sur-ensemble qui les ajoute:

• CommonMark
• GitHub Flavored Markdown (GFM)
• Markdown Extra
• MultiMarkdown
• R Markdown

Toutes les applications Markdown ne prennent pas en charge ces éléments de syntaxe étendue — vérifiez quel langage de balisage léger la cible prend en charge.

Pour ajouter un tableau, utilisez la barre verticale | pour séparer les colonnes et trois tirets --- ou plus pour créer l’en-tête de chaque colonne. Ajoutez une barre verticale à chaque extrémité de la ligne:

| Month    | Savings |
| -------- | ------- |
| January  | $250    |
| February | $80     |
| March    | $420    |

Le rendu ressemble à ceci:

Alignez le texte des colonnes en ajoutant un deux-points : à gauche, à droite ou des deux côtés des tirets --- dans la ligne d’en-tête:

• :-- signifie que la colonne est alignée à gauche
• --: signifie que la colonne est alignée à droite
• :-: signifie que la colonne est centrée

| Item              | In Stock | Price |
| :---------------- | :------: | ----: |
| Python Hat        |   True   | 23.99 |
| SQL Hat           |   True   | 23.99 |
| Codecademy Tee    |  False   | 19.99 |
| Codecademy Hoodie |  False   | 42.99 |

Le texte peut être mis en forme dans les tableaux: les liens, l’emphase et le code en ligne (mots ou phrases entre accents graves seulement, pas les blocs de code) fonctionnent tous. Les titres, les citations, les lignes horizontales, les images, les listes et les balises HTML ne fonctionnent pas.

Affichez une barre verticale dans un tableau en l’échappant avec \| ou avec son code de caractère HTML |.

Listes de définitions#

Certains processeurs Markdown permettent de créer des listes de définitions de termes et de leurs définitions. Pour en créer une, tapez le terme sur la première ligne. Sur la ligne suivante, tapez un deux-points suivi d’une espace et de la définition:

First Term
: This is the definition of the first term

Second Term
: This is one definition of the second term
: This is another definition of the second term

Le HTML ressemble à ceci:

<dl>
  <dt>First Term</dt>
  <dd>This is the definition of the first term.</dd>
  <dt>Second Term</dt>
  <dd>This is one definition of the second term.</dd>
  <dd>This is another definition of the second term.</dd>
</dl>

Notes de bas de page#

Les notes de bas de page ajoutent des remarques et des références sans encombrer le corps du document. Un appel de note s’affiche comme un chiffre en exposant qui pointe vers la note au bas de la page, et Hugo génère un lien de retour marqué ↩ pour que la personne revienne du texte de la note à l’endroit d’origine. Les notes de bas de page via l’extension Footnote sont activées par défaut.

Readers can click the link[^1] to jump to the content of the footnote.

[^1]: The footnote text goes here.

Les définitions peuvent être tapées n’importe où dans le fichier .md; Hugo les déplace tout au bas de la page rendue. Font exception les définitions placées dans d’autres éléments comme les listes, les citations et les tableaux, qui ne bougent pas.

Si une note doit s’étendre sur plusieurs paragraphes, indentez les paragraphes suivants de quatre espaces ou d’une tabulation et Hugo les gardera dans la zone de la note.

Pour changer l’apparence de la section des notes, ciblez les classes CSS .footnotes et .footnote-backref dans la feuille de style du thème.

Échappement de caractères#

Pour afficher un caractère littéral qui servirait autrement à mettre le texte en forme, ajoutez une barre oblique inverse (\) devant le caractère:

\* Without the backslash, this would be a bullet in an unordered list.

Une barre oblique inverse peut échapper les caractères suivants:

Emoji#

Il y a deux façons courantes d’ajouter un emoji dans un fichier Markdown: copier-coller l’emoji dans le texte, ou utiliser le shortcode emoji du site.

Dans la plupart des cas, on peut copier un emoji depuis une source comme Emojipedia et le coller dans le document. Beaucoup d’applications Markdown affichent directement l’emoji dans le texte Markdown. Les exports HTML et PDF devraient aussi l’afficher, tant que le document et le format de sortie prennent en charge le caractère.

Certaines applications Markdown permettent d’insérer un emoji avec un shortcode. Ces shortcodes commencent et se terminent par deux-points et contiennent le nom d’un emoji:

Parti camper! :tent: De retour bientôt.
C'est tellement drôle! :joy:

Parti camper! ⛺ De retour bientôt.
C’est tellement drôle! 😂

Les noms de shortcodes varient selon les applications. Sur ce site, utilisez le shortcode emoji, qui lit la table d’emojis maintenue dans data/series/ref/emojis.yml:

{{< emoji "warning" >}}

Les sources auxquelles cette table fait confiance pour les noms, les points de code et les shortcodes sont documentées sur la page Mécanique d’écriture.