PHP Markdown : Concepts

Ce document introduit les différents concepts qui vous permettront d’écrire selon la syntaxe Markdown.

Une fois familiarisé avec la syntaxe, une bonne façon d’apprivoiser Markdown est de s’entraîner à l’aide du banc d’essai (voir le menu ci-haut).

Paragraphes

Un paragraphe est constitué d’une ou plusieurs lignes consécutives de texte, séparées par une ou plusieurs lignes vides :

Voici un petit paragraphe servant à illustrer le 
fonctionnement de Markdown. Ce paragraphe s'étend
sur plus d'une ligne.

Voici un deuxième paragraphe.

Ceci donne le résultat suivant :

Les sauts de ligne insérés dans le texte disparaissent dans le résultat final : c’est le navigateur qui se charge de couper les lignes en fonction de l’espace disponible. Si vous désirez véritablement forcer un saut de ligne à un certain endroit, vous n’avez qu’à insérer deux espaces à la fin de la ligne.

Emphase

Vous pouvez mettre en emphase une partie du texte d’un paragraphe. Il existe deux types d’emphase : l’emphase normale et l’emphase forte. Sur la plupart des sites web, l’emphase correspond à du texte en italique, en gras pour l’emphase forte.

Pour donner de l’emphase au texte avec Markdown, on utilise les astérisques (*) ou les traits soulignés (_). Entourer du texte d’un astérisque ou d’un trait souligné crée une emphase normale, alors qu’entourer le texte avec deux astérisques ou deux traits soulignés donne une emphase forte :

*emphase normale avec astérisques*

_emphase normale avec traits soulignés_

**emphase forte avec astérisques**

__emphase forte avec des traits soulignés__

Voici du texte *mis en emphase* avec des astérisques.

Ceci donne le résultat :

Notez bien qu’il n’y a aucune différence entre les traits soulignés et les astérisques : les deux donnent exactement le même résultat. Choisissez la variante qui vous convient le mieux.

Liens

Si vous désirez insérer un lien hypertexte à l’intérieur de votre document, Markdown vous permet de le faire de deux façons. Vous pouvez utiliser un lien incorporé ou par référence.

Le lien incorporé vous permet de lier du texte à une autre page web. Entourez le texte à lier de [crochets], puis ajoutez l’adresse entre parenthèses juste après. Comme ceci :

[Michel Fortin](https://michelf.ca/)

[Michel Fortin](https://michelf.ca/ "Mon site web")

Le deuxième lien possède un titre (entre guillemets) qui est généralement affiché sous la forme d’une bulle d’aide quand vous placez votre curseur au dessus du lien. Le titre est optionnel.

Le lien par référence fonctionne de la même façon, sauf que vous n’avez pas à écrire l’adresse au milieu du paragraphe, ce qui rend le texte plus lisible. À la place, vous donnez un nom au lien et vous écrivez l’adresse sur une ligne à part — n’importe où dans le document. Comme ceci :

Voici un petit texte écrit par [Michel Fortin][mf].

 [mf]: https://michelf.ca/ "Mon site web"

La ligne qui sert à spécifier l’adresse est retirée du résultat final et le texte devient un lien :

Encore une fois, le titre du lien (Mon site web) peut être omis.

Liens automatiques

Si vous désirez simplement transformer une adresse internet en un lien cliquable, placez l’adresse entre chevrons et Markdown en fera un lien :

<https://michelf.ca/>

<michel.fortin@michelf.ca>

Titres

Vous pouvez ajouter des titres et des sous-titres à votre document avec Markdown. Deux syntaxes vous permettent de placer des titres à six niveaux différents. Vous pouvez faire des titres de niveau 1 et 2 à l’aide de la syntaxe « SeText » :

Titre 1
=======

Titre 2
-------

La syntaxe « atx » vous permet de créer des titres à tous les niveaux en variant le nombre de dièses :

# Titre 1 #

## Titre 2 ##

###### Titre de niveau 6

Vous remarquerez aussi que les dièses à droite du titre sont facultatifs.

Citation

Peut-être avez vous déjà observé cette façon d’indiquer une citation dans une discussion par courrier électronique :

Une citation sur l'analyse numérique :

> La méthode de différenciation de Richardson est valable
> non seulement pour la différentiation et l'intégration 
> numériques, mais aussi pour l'interpolation, la résolution 
> numérique des équations différentielles.

Vous pouvez placer plusieurs paragraphes à l’intérieur d’un bloc de citation. Vous pouvez aussi insérer à l’intérieur un deuxième niveau de citation, des listes, etc.

Listes

Markdown vous permet de créer des listes numérotées (dites ordonnées) ou des listes à pastilles (dites non-ordonnées). Pour créer une liste ordonnée, utilisez un chiffre suivi d’un point comme marqueur :

1.  Hiboux
2.  Choux
3.  Genoux

Pour créer une liste non-ordonnée, utilisez *, + ou - comme marqueur :

*   Soleil
*   Lune
*   Terre

Vous pouvez imbriquer des listes en indentant de 4 espaces (ou d’une tabulation) les listes qui sont au deuxième niveau :

*   Ingrédients
    -   Lait
    -   Oeuf
*   Recette
    1.  Mélanger
    2.  Fouetter

Si votre liste contient des paragraphes, laissez une ligne blanche entre les différents éléments de la liste. Pour écrire plusieurs paragraphes sous un même marqueur de liste, assurez vous que les paragraphes supplémentaires sont indentés de 4 espaces (ou une tabulation) :

1.  Premier paragraphe.

    Deuxième paragraphe.

2.  Un nouvel élément.

3.  Encore un autre.

Code

Bloc de code

On écrit un bloc de code en indentant de quatre espaces (ou d’une tabulation) une section du texte :

Code pour mettre de l'emphase :

    Selon le <em>HTML</em> et selon *Markdown*.

À l’intérieur d’un bloc de code, vous pouvez placer des balises HTML ou du formattage Markdown ; dans les deux cas, la syntaxe ne sera pas interprétée et le texte sera affiché tel quel :

Selon le <em>HTML</em> et selon *Markdown*.

Dans le texte

Vous pouvez créer une étendue de code dans le texte d’un paragraphe en utilisant les guillemets obliques (un simple accent grave: `), de cette façon :

N'utilisez pas la balise `<blink>` sur vos pages web.

Ce qui donnera le résultat suivant :

HTML

Vous n’avez pas à connaître le HTML pour utiliser Markdown. Cependant si vous connaissez certaines balises HTML, vous pouvez en tout temps les intercaler là où vous en avez besoin. Par exemple, pour mettre du texte en exposant — ce qui n’est pas couvert par Markdown — vous pouvez utiliser la balise <sup> :

Méfions-nous du 1<sup>er</sup> avril !

Markdown passe par dessus la balise sans y toucher et le navigateur la reconnaît et affiche le texte à l’intérieur en exposant :

Certaines balises telle <p> et <div> identifient des blocs de texte. Si vous utilisez ces balises, des règles spéciales s’appliquent. Voyez la section HTML intercalé de la description de la syntaxe pour plus de détails.