Balises et mise en forme

Titre 1

Titre 2

Titre 3

Titre 4

Titre 5
titre 6

Blocs de citation

Sur une ligne :

Plus on partage, plus on possède. Voilà le miracle.

Multi ligne avec une référence d’auteur :

C’est notre Charte. Stallman l’a appelé le Logiciel Libre. Le « libre » n’a rien à voir avec le prix, même si vous êtes toujours libre de faire payer pour votre logiciel, mais avec la liberté de créer. Ou comme nous geeks nous disons souvent : pas libre comme l’air, libre comme dans les paroles. Matt Mullenweg – Fondateur de WordPress ‘ extrait de l’article The Four Freedoms, 2014

Tableaux

Intervenant Salaire
Benjamin Lupu 1 € Parce que c’est ce que Steve Job avaient besoin comme salaire.
Remi Corson 100 m € Pour tout le taf qu’il fait.
Gregoire Noyelle 10 mns € Les images valent mille mots, non ? Alors avec un chapeau comme ça.
BoiteAWeb 10 mds € La sécurité n’a pas de prix !

Listes de définitions

Titre de la liste
Division de la liste.
CMS
Un système de gestion de contenu ou SGC (Content Management System ou CMS) est une famille de logiciels destinés à la conception et à la mise à jour dynamique de sites Web ou d’applications multimédia. Vous pensez à quoi ?
#hashtag
Un marqueur de métadonnées couramment utilisé sur internet où il permet de marquer un contenu avec un mot-clef plus ou moins partagé sur les IRC et réseaux sociaux.
Rapper’s Delight
Laissons Brian Williams nous le dire personnellement.

Listes non ordonnées (Imbriquées)

  • Premier élément de la liste
    • Premier élément de la liste
      • Premier élément de la liste
      • Deuxième élément de la liste
      • Troisième élément de la liste
      • Quatrième élément de la liste
    • Deuxième élément de la liste
    • Troisième élément de la liste
    • Quatrième élément de la liste
  • Deuxième élément de la liste
  • Troisième élément de la liste
  • Quatrième élément de la liste

Listes ordonnées (Imbriquées)

  1. Premier élément de la liste
    1. Premier élément de la liste
      1. Premier élément de la liste
      2. Deuxième élément de la liste
      3. Troisième élément de la liste
      4. Quatrième élément de la liste
    2. Deuxième élément de la liste
    3. Troisième élément de la liste
    4. Quatrième élément de la liste
  2. Deuxième élément de la liste
  3. Troisième élément de la liste
  4. Quatrième élément de la liste

Balises HTML

Ces balises proviennent du code de WordPress.com FAQ.

Balises d’adresse

1 rue de la Boucle Infinie
Cupertino, CA 95014
United States

Balise d’ancre (alias Lien)

C’est un exemple de lien.

Balise d’abbréviation

L’abbréviation TSVP signifie ici « Testez S’il Vous Plaît ».

Acronyme

L’acronyme www signifie le « web ».

Balise big

C’est tests n’ont rien à voir avec lebigdil de Bigard, en plus cette balise n’est même plus supportée en HTML5.

Balise de citation

« If Code is poetry, Translation helps it spread the world » —Automattic + FxB

Balise de code

Vous verrez plus tard dans les tests que  word-wrap: break-word; sera votre meilleure amie.

Balise de suppression

Cette balise devrait barré ce texte, mais cette balise n’est même plus supportée en HTML5 (utilisez <strike> à la place).

Balise d’emphase

La balise d’emphase devrait mettre en italique le texte.

Balise d’insertion

Cette balise devrait indiquée un texte inséré.

Balise Keyboard

Cette balise très peu connue simule du texte clavier, et qui généralement utilise le même style que la balise <code>.

Balise de Preformatage

Cette balise permet de styliser de grands blocs de code.

.post-title {
    margin: 0 0 5px;
    font-weight: bold;
    font-size: 38px;
    line-height: 1.2;
}

Balise de citation

Développeurs, développeurs, développeurs… –Steve Ballmer

Balise strong

Cette balise affiche du texte en gras.

Balise subscript

Une petite dose de style pour notre H2O, qui devrait pousser le « 2 » vers le bas.

Balise superscript

Toujours s’en tenir à la science et au E = MC2 d’Albert Einstein, qui devrait voir son 2 sous forme de puissance.

Balise teletype

Cette balise rarement utilisée simule du texte teletype, et qui généralement utilise le même style que la balise <code>.

Balise de variables

Cela vous permet d’indiquer des variables.

Markdown

Cet article utilise la syntaxe Markdown. Installez Jetpack ou WP-Markdown, activez le module « Markdown » et admirez le rendu. Bluffant, non !

Philosophie

## Philosophie

Markdown a été conçu pour être aussi facile à lire et à écrire que possible. La lisibilité, cependant, prime devant tout le reste. Un document formaté selon Markdown devrait pouvoir être publié comme tel, en texte, sans donner l’impression qu’il a été marqué par des balises ou des instructions de formatage. Bien que la syntaxe Markdown ait été influencée par plusieurs filtres de conversion de texte vers HTML existants — incluant Setext, atx, Textile, reStructuredText, Grutatext, et EtText — la source d’inspiration principale de la syntaxe Markdown est le format du courrier électronique en mode texte.

incluant [Setext] [1], [atx] [2], [Textile] [3], [reStructuredText] [4],[Grutatext] [5], et [EtText] [6] — la source d’inspiration principale de la syntaxe Markdown est le format du courrier électronique en mode texte.

[1]: http://docutils.sourceforge.net/mirror/setext.html
[2]: http://www.aaronsw.com/2002/atx/
[3]: http://textism.com/tools/textile/
[4]: http://docutils.sourceforge.net/rst.html
[5]: http://www.triptico.com/software/grutatxt.html
[6]: http://ettext.taint.org/doc/

À cette fin, la syntaxe de Markdown est constituée entièrement de caractères de ponctuation, des caractères choisis soigneusement afin que leur apparence évoque la signification donnée par la syntaxe. Par exemple, des astérisques placés autour d’un mot donnent l’impression que l’on met l’emphase sur ce mot. Les listes dans Markdown ressemblent à.. des listes, évidemment. Même les blocs de citation ressemblent à des passages de texte cités, en supposant que vous ayez déjà envoyé ou reçu du courrier électronique.

HTML intercalé

## HTML intercalé

La syntaxe de Markdown sert un objectif : être utilisée comme format d’écriture sur le web.

Markdown n’est pas un remplacement pour le HTML, ni même près de l’être. Sa syntaxe est petite et correspond en fait à un très petit sous-ensemble du HTML. L’idée n’est pas de créer une syntaxe qui rend plus facile l’insertion de balises HTML. Selon moi, ces balises sont déjà faciles à insérer. L’idée derrière Markdown est de faciliter la lecture, l’écriture et l’édition du texte en prose. L’HTML est un format de publication, Markdown est un format d’écriture. C’est pour cette raison que Markdown s’adresse uniquement à ce qui peut être transmis par du texte.

Pour n’importe quelle fonction qui n’est pas couverte par la syntaxe de Markdown, vous utilisez directement une balise HTML. Il n’y a pas de raison de la précéder ou de la délimiter par des marqueurs spéciaux indiquant le passage de la syntaxe Markdown au HTML; vous écrivez tout simplement la balise là où vous la voulez.

Les seules restrictions sont que les éléments HTML représentant un bloc de texte — c’est à dire, <div>, <table>, <pre>, <p>, etc.. — doivent être séparés du contenu environnant par des lignes vides, et les balises de début et de fin ne doivent pas êtres indentées avec des tabulations ou des espaces. Markdown est assez intelligent pour ne pas ajouter des balises supplémentaires (et indésirables) autour des éléments de bloc.

Par exemple, pour ajouter un tableau HTML à un article écrit avec Markdown :

Ceci est un paragraphe régulier.

Foo

Ceci est un autre paragraphe régulier.

Notez que le formatage Markdown n’est pas appliqué à l’intérieur des balises d’élément de blocs HTML. C’est à dire que vous ne pouvez pas appliquer de l’emphase selon la syntaxe Markdown à l’intérieur d’un bloc HTML.

Les éléments délimitant une étendue de texte — comme <cite> ou <del> — peuvent être utilisés n’importe où dans un paragraphe, dans l’élément d’une liste ou dans un titre. Si vous voulez, vous pouvez même utiliser des balises HTML à la place du format Markdown; par exemple si vous préférez utiliser la balise HTML <a> ou <img/> au lieu de la syntaxe Markdown pour les liens ou les images, faites-le.

Contrairement aux éléments de bloc, la syntaxe Markdown est traitée à l’intérieur des balises étendue de texte.

Échappement automatique des caractères spéciaux

## Échappement automatique des caractères spéciaux

En HTML, il y a deux caractères qui demandent un traitement spécial : < et &. Les chevrons ouvrants sont utilisés pour débuter les balises ; les esperluettes indiquent une entité HTML. Si vous voulez les utiliser en tant que caractères littéraux, vous devez les échapper avec des entités, c’est à dire que vous devez écrire &lt;, et
&amp;.

Paragraphes et saut de ligne

## Paragraphes et saut de ligne

Un paragraphe est simplement une ou plusieurs lignes consécutives de texte, séparées par une ou plusieurs lignes vides. (Une ligne contenant uniquement des espaces ou des tabulations est considérée vide.) Les paragraphes ne doivent normalement pas êtres indentés par des espaces ou des tabulations.

La règle « une ou plusieurs lignes consécutives de texte » implique que Markdown supporte les sauts de ligne manuels à l’intérieur des paragraphes. Ceci diffère beaucoup de la plupart des autres convertisseurs de texte vers HTML (incluant l’option « Convertir les sauts de ligne » de MovableType) qui traduisent chaque saut de ligne à l’intérieur d’un paragraphe par la balise <div> <cite> <del> <a>.

Si vous voulez vraiment insérer une balise de saut de ligne <br /> en utilisant Markdown, vous n’avez qu’à terminer la ligne par deux espaces, ou plus, puis taper « entrée ».

Oui, ceci nécessite un peu plus d’effort pour créer un <br />, mais une règle plus simple dans le style de « chaque saut de ligne correspond à un <br /> ne fonctionnerait pas bien pour Markdown. La syntaxe des blocs de citation et des listes à plusieurs paragraphes fonctionne mieux — tout en étant plus lisible — quand vous formatez vos paragraphes avec un saut de ligne à la fin de chaque ligne.

Titres

## Titres

Markdown supporte deux syntaxes pour les titres, Setext et atx. Les titres de style Setext sont « soulignés » en utilisant le symbole égal (pour le premier niveau) et des tirets (pour le second niveau). Par exemple :

Titre de niveau 1 (balise H1)

Titre de niveau 2 (balise H2)

Titre de niveau 1 (balise H1)
=============
Titre de niveau 2 (balise H2)
-------------

N’importe quelle longueur de soulignement avec des = ou des – fonctionne. Les titres de style atx sont représentés par entre un et six dièses (#) au début de la ligne, représentant les titres de niveau 1 à 6. Par exemple :

Titre de niveau 1

Titre de niveau 2

Titre de niveau 6
# Titre de niveau 1
## Titre de niveau 2
###### Titre de niveau 6

Facultativement, vous pouvez « fermer » les titres de style atx. C’est purement esthétique — faites-le si vous trouvez que c’est plus beau. Le nombre de dièses de fermeture n’a pas besoin de correspondre au nombre utilisé au début l’entête. (Le nombre de dièses ouvrant détermine le niveau du titre.) :

# Titre de niveau 1 #
## Titre de niveau 2 ##
###### Titre de niveau 6 ##

Blocs de citation

## Blocs de citation

Comme pour le courrier électronique, Markdown utilise le caractère > pour délimiter les blocs de citation. Si vous êtes familier avec le format de citation du courrier électronique, alors vous savez comment créer un bloc de citation avec Markdown. Le résultat est plus joli si le texte est écrit avec des sauts de ligne manuels et un > au début de chaque ligne :

Ceci est un bloc de citation avec deux paragraphes.
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.

> Ceci est un bloc de citation avec deux paragraphes. 
> Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. 
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. 

>Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
>Suspendisse id sem consectetuer libero luctus adipiscing.

Markdown vous permet cependant d’être paresseux et de n’écrire qu’un seul > au début de la première ligne d’un paragraphe à sauts de ligne manuels :

Ceci est un bloc de citation avec deux paragraphes.
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.

> Ceci est un bloc de citation avec deux paragraphes. 
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. 
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. 

>Donec sit amet nisl. Aliquam semper ipsum sit amet velit. 
Suspendisse id sem consectetuer libero luctus adipiscing.

Les blocs de citation peuvent être imbriqués (c’est à dire qu’on a un bloc de citation à l’intérieur d’un autre bloc de citation) en ajoutant des niveaux additionnels de > :

Ceci est le premier niveau de citation.

Ceci est un bloc de citation imbriqué.

Retour au premier niveau.

> Ceci est le premier niveau de citation.
>
> > Ceci est un bloc de citation imbriqué.
>
> Retour au premier niveau.

Les blocs de citation peuvent contenir d’autres éléments de Markdown, comme des titres, des listes et des blocs de code :

Ceci est un titre.

  1. Ceci est le premier élément d’une liste.
  2. Ceci est le second élément d’une liste.

Voici un exemple de code :

return shell_exec(« echo $input | $markdown_script »);

>## Ceci est un titre.
>
> 1. Ceci est le premier élément d’une liste.
> 2. Ceci est le second élément d’une liste.
>
    > Voici un exemple de code :
    >
    >    return shell_exec(« echo $input | $markdown_script »);

Un éditeur de texte qui se respecte devrait permettre facilement de créer des blocs de citations comme dans un e-mail. Par exemple, avec BBEdit, vous pouvez sélectionner du texte et choisir «Augmenter le niveau de citation» dans le menu Texte.

Listes

## Listes

Markdown supporte les listes ordonnées (numérotées) et non-ordonnées (à puces). Les listes non-ordonnées utilisent l’astérisque, le plus, ou encore le tiret — de façon tout à fait interchangeable — en tant que marqueur de liste :

* Rouge
* Vert
* Bleu

est équivalent à :

- Rouge
- Vert
- Bleu

et à :

+ Rouge
+ Vert
+ Bleu

et correspondent à :

  • Rouge
  • Vert
  • Bleu

Les listes ordonnées utilisent un nombre suivit d’un point :

1. Parker
2. Batum
3. Diaw

Il est important de noter que l’ordre des nombres que vous utilisez pour écrire la liste n’a pas d’effet sur la sortie HTML que Markdown produit. Le code HTML produit par Markdown à partir du texte ci-dessus est :

  1. Parker
  2. Batum
  3. Diaw

Si vous écrivez la liste comme ceci :

1. Parker
1. Batum
1. Diaw

ou même :

8. Parker
3. Batum
1. Diaw

vous obtiendriez exactement le même code HTML en sortie. L’idée est que, si vous voulez, vous pouvez utiliser des nombres ordinaux dans vos listes ordonnées faites avec Markdown, de façon à ce que les nombres dans votre texte d’entrée correspondent avec ceux du résultat HTML. Mais si vous préférez, vous n’avez pas à le faire.

Toutefois, si vous ne numérotez pas les éléments dans l’ordre, vous devriez quand même débuter vos listes avec le numéro 1. Il est possible que Markdown supporte dans le futur des listes ordonnées commençant par un numéro quelconque.

Les marqueurs de liste sont typiquement alignés sur la marge de gauche, mais peuvent être indentés de la marge par trois espaces ou moins. Les marqueurs de liste doivent être suivis par au moins une espace, ou par une tabulation.

Pour écrire une liste qui se lit bien, vous pouvez ajouter une indentation après chaque saut de ligne manuel :

  • Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
    Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

  • Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
    Suspendisse id sem consectetuer libero luctus adipiscing.

Mais si vous préférez vous éviter du travail, vous n’avez pas à le faire :

  • Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
    Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

  • Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
    Suspendisse id sem consectetuer libero luctus adipiscing.

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. 
       Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit. 
       Suspendisse id sem consectetuer libero luctus adipiscing.

Si les éléments de la liste sont séparés par une ligne blanche, Markdown placera leur contenu à l’intérieur de balises dans la sortie HTML. Par exemple, cette entrée :

* Oiseau 
* Magie 

sera changée en :

  • Oiseau
  • Magie

Alors que ceci :

* Oiseau

* Magie

sera changé en :

  • Oiseau

  • Magie

Les éléments d’une liste peuvent être constitués de plusieurs paragraphes. Tous les paragraphes suivants le premier doivent à ce moment être indentés par 4 espaces ou une tabulation :

1.  Ceci est un élément de la liste contenant deux paragraphes. 
    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 
    Aliquam hendrerit mi posuere lectus.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    sit amet velit.

2.  Suspendisse id sem consectetuer libero luctus adipiscing.

Le résultat est plus beau si vous indentez toutes les lignes des paragraphes, mais ici aussi Markdown vous permet d’être un peu souple :

*   Ceci est un élément de la liste avec deux paragraphes.

    Ceci est le deuxième paragraphe dans l'élément. Vous

n’avez besoin d’indenter que la première ligne. Lorem ipsum
dolor sit amet, consectetuer adipiscing elit.

*   Un autre élément dans la même liste.

Pour mettre un bloc de citation à l’intérieur d’un élément d’une liste, les délimiteurs > du bloc de citation doivent être indentés :

*   Un élément de la liste avec une citation :

    > C'est une citation
    > à l'intérieur d'une liste.

Pour placer un bloc de code à l’intérieur de l’élément d’une liste, le bloc de code doit être indenté deux fois (une fois pour la liste et une fois pour le bloc de code), ce qui représente 8 espaces ou deux tabulations :

*   Un élément de liste avec un bloc de code :

        <le code vient ici>

Il vaut la peine de noter qu’il est possible de déclencher une liste ordonnée par accident, en écrivant quelque chose comme ça :

2014. Quelle belle année en prévision.

En d’autre mots, une séquence nombre-point-espace au début d’une ligne. Pour éviter cette situation, vous pouvez échapper le point à l’aide d’une barre oblique inverse :

2014\. Quelle belle année en prévision.

Blocs de code

## Blocs de code

Les blocs de code sont utilisés pour écrire du code de programmation ou de balisage HTML. À la place de former des paragraphes normaux, les lignes d’un bloc de code sont interprétées littéralement. Markdown enveloppe un bloc de code avec les deux balises <pre> et <code>.

Pour produire un bloc de code avec Markdown, vous n’avez qu’à indenter chaque ligne d’un bloc par au moins 4 espaces ou une tabulation. Par exemple, avec ce texte en entrée :

Ceci est un paragraphe normal :

    Ceci est un bloc de code.

Markdown générera :

Ceci est un paragraphe normal :

Ceci est un bloc de code.

Un niveau d’indentation — 4 espaces ou une tabulation — est enlevé de chaque ligne du bloc de code. Par exemple, ceci :

Voici un exemple d’AppleScript :
tell application « Foo »
beep
end tell
Markdown générera :

Voici un exemple d’AppleScript :

tell application "Foo"
    beep
end tell

Un bloc de code se termine à la première ligne qui n’est pas indentée (ou en atteignant la fin de l’article). À l’intérieur d’un bloc de code, l’esperluette (&) et les chevrons (< et >) sont automatiquement convertis en entités HTML. Ceci permet d’inclure très facilement des exemples de code HTML en utilisant Markdown — juste à le coller et à l’indenter, et Markdown s’occupera d’encoder l’esperluette et les chevrons. Par exemple, ceci :

<div class="footer">
    &copy; 2014 Foo Corporation
</div>

sera converti en :

<div class="footer">
    &copy; 2004 Foo Corporation
</div>

La syntaxe Markdown n’est pas traitée à l’intérieur d’un bloc de code. Ceci signifie qu’il est aussi très facile d’utiliser Markdown pour écrire des exemples portant sur sa propre syntaxe.

Lignes horizontales

## Lignes horizontales

Vous pouvez produire une ligne horizontale


en plaçant au moins trois tirets, astérisques, ou barres de soulignement seuls sur une ligne. Si vous voulez, vous pouvez aussi écrire des espaces entre les tirets ou les astérisques. Chacune des lignes suivante produira une ligne horizontale :

* * *
***
*****
- - -
---------------------------------------
_ _ _

Éléments de texte

## Éléments de texte

Liens

Markdown supporte deux styles de liens : incorporé au texte et par référence.

Dans les deux cas, le texte du lien est délimité par des [crochets].

Pour créer un lien incorporé au texte, insérez une parenthèse immédiatement après le crochet qui ferme le texte du lien. À l’intérieur de la parenthèse, placez l’URL sur lequel vous voulez faire pointer le lien, optionnellement accompagné d’un titre pour le lien entouré de guillemets droits. Par exemple :

Ceci est [un exemple](http://exemple.com/ "Titre") de lien incorporé.

Produira :

Ceci est
un exemple
de lien incorporé.

Ce lien n’a pas de
titre.

Si vous faites référence à une ressource locale sur le même serveur, vous pouvez utiliser un chemin relatif :

Voir ma page [Description](/description/) pour les détails. 

Les liens par référence utilisent une deuxième paire de crochets, à l’intérieur desquels vous placez une étiquette pour identifier le lien :

Ceci est [un exemple][id] de lien en référence.

Vous pouvez facultativement utiliser une espace pour séparer les deux crochets :

Ceci est [un exemple] [id] de lien en référence.

Ensuite, n’importe où dans le document, vous définissez le lien de cette façon, sur sa propre ligne. En résumé :

  • Des crochets contenant le nom du lien (pouvant être indentés de la marge de gauche par au plus trois espaces);
  • suivis d’un deux-points;
  • suivi d’une espace ou plus (ou des tabulations);
  • suivi par l’URL du lien;
  • optionnellement suivi d’un titre entouré par des guillemets droits simples ou doubles.

L’URL du lien peut, mais ce n’est pas obligatoire, être entourée par des chevrons :

[id]: <http://exemple.com/>  "Titre facultatif"

Vous pouvez placer l’attribut titre sur la ligne suivante et utiliser des espaces supplémentaires ou des tabulations pour faire du remplissage, ce qui donne un plus beau résultat avec de longues URLs :

[id]: http://exemple.com/long/chemin/vers/la/ressource
"Titre facultatif"

Les définitions de liens sont utilisées uniquement pour créer des liens durant le traitement par Markdown, et sont supprimées du document HTML en sortie. Les noms des liens peuvent contenir des lettres, des nombres, des espaces et de la ponctuation — mais ils ne sont pas sensibles à la casse. Par exemple, ces deux liens :

[lien du texte][a] et [lien du texte][A]

sont équivalents.

Vous pouvez utiliser un nom de lien implicite, ce qui vous permet d’omettre le nom du lien, et dans ce cas le lien est identifié par son texte. Utilisez simplement une paire de crochets vides — c’est à dire que pour créer un lien « Google » vers le site google.com, vous pouvez simplement écrire :

[Google][]

Et ensuite définir le lien :

[Google]: http://google.com/

Parce que le nom du lien peut contenir des espaces, ce raccourci fonctionne aussi quand vous avez plusieurs mots dans le texte lié :

Visitez [Daring Fireball][] pour plus d'informations.

Et ensuite définissez le lien :

[Daring Fireball]: http://daringfireball.net/

Les définitions de lien peuvent être placées n’importe où dans le document Markdown. J’ai tendance à les placer immédiatement après le paragraphe dans lequel elles sont utilisées, mais si vous voulez, vous pouvez les placer à la fin de votre document, comme des notes de bas de page. Voici un exemple qui montre les liens par référence en action :

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

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

En utilisant les noms de liens implicites, vous pourriez écrire :

Je reçois 10 fois plus de trafic de Google[] que de Yahoo[] ou de Bing[].

  [google]: http://google.com/        "Google"
  [yahoo]: http://search.yahoo.com/  "Yahoo Search"
  [bing]: http://bing.com/    "Bing Search" 

Les deux exemples ci-dessus produiront le code HTML suivant :

Je reçois 10 fois plus de trafic de Google que de Yahoo ou Bing.

En guise de comparaison, voici le même paragraphe écrit avec la syntaxe de lien incorporées :

Je reçois 10 fois plus de trafic de [Google](http://google.com/ "Google") que de [Yahoo](http://search.yahoo.com/ "Yahoo Search") ou [Bing](http://bing.com/ "Bing Search").

Le but des liens par référence n’est pas qu’ils soient plus faciles à écrire. L’idée est qu’avec les liens par référence, votre document est beaucoup plus lisible. Comparez les exemples ci-dessus : en utilisant les liens par référence, le paragraphe contient seulement 81 caractères, avec les liens incorporés au texte nous avons 176 caractères, et sous forme de code HTML, c’est 234 caractères.

En HTML, il y a plus de balises que de texte. Avec les liens par référence de Markdown, un document source ressemble beaucoup plus à sa sortie finale, tel qu’il sera affiché dans votre navigateur. En vous permettant de prendre les informations supplémentaires reliées aux liens et de les placer en dehors du paragraphe, vous pouvez créer des liens sans interrompre l’écoulement narratif de votre texte.

Emphase

Markdown interprète les astérisques * et les traits soulignés _ pour indiquer l’emphase. Du texte placé entre deux * ou _ sera entouré par l’élément HTML <em> ; avec des doubles * ou _, le texte sera entouré de l’élément <strong>. Par exemple, cette entrée :

*astérisques simples*

_traits soulignés simples_

**astérisques double**

__traits soulignés doubles__

produira :

astérisques simples

traits soulignés simples

astérisques double

traits soulignés doubles

Vous pouvez utiliser le style que vous préférez; la seule restriction est que le même caractère doit être utilisé pour ouvrir et fermer l’emphase. L’emphase peut être utilisée au milieu d’un mot :

un*fucking*believable 

Mais si vous placez un * ou _ entre deux espaces, il sera traité littéralement comme un astérisque ou un trait de soulignement. Pour produire un astérisque littéral à un endroit où il serait autrement utilisé comme délimiteur d’emphase, vous pouvez l’échapper à l’aide d’une barre oblique inverse :

\*ce texte est entouré d'astérisques litéraux\*

Code

Pour indiquer une étendue de code, entourez-la de guillemets obliques (un accent grave solitaire : `). Contrairement aux blocs de code, une étendue de code signale du code à l’intérieur d’un paragraphe. Par exemple :

Utilisez la fonction `printf()` pour afficher.

produira :

Utilisez la fonction printf() pour afficher.

Pour écrire des guillemets obliques dans une étendue de code, vous pouvez utiliser plusieurs apostrophes obliques pour ouvrir et fermer l’étendue de code :

``Il y a un guillemet oblique (`) ici.``

Il y a un guillemet oblique () ici. produira :

Il y a un guillemet oblique (`) ici.

Les délimiteurs de l’étendue de code peuvent inclure des espaces — une après le guillemet d’ouverture, une après celui de fermeture. Ceci vous permet de placer un guillemet oblique littéral au début et à la fin de l’étendue de code :

Un guillemet oblique dans une étendue de code : `` ` ``

Du texte délimité par des guillemets obliques dans une étendue de code : `` `foo` ``

produira :

Un guillemet oblique dans une étendue de code : `

Du texte délimité par des guillemets obliques dans une étendue de code : `foo`

Dans une étendue de code, l’esperluette et les chevrons sont encodés en entités HTML automatiquement, ce qui permet d’ajouter facilement des exemples de balises HTML. Markdown convertira ceci :

N'utilisez pas `<blink>` s'il vous plaît.

produira :

N’utilisez pas <blink> s’il vous plaît.

Vous pouvez écrire ceci :

`&#8212;` est l'équivalent décimal de `&mdash;`.

produira :

&#8212; est l’équivalent décimal de &mdash;.

Images

## Images

En effet, c’est plutôt difficile de construire une syntaxe « naturelle » pour placer des images dans un document texte.

Markdown utilise une syntaxe d’image qui ressemble à la syntaxe des liens, permettant deux variantes : incorporé et par référence.

La syntaxe des images incorporées ressemble à ceci :

![Texte alternatif](/chemin/vers/img.jpg)

![Texte alternatif](/chemin/vers/img.jpg "Titre optionnel")

C’est à dire :

  • Un point d’exclamation : ! ;
  • suivi d’une paire de crochets contenant le texte de l’attribut alt de l’image ;
  • suivi par une parenthèse, contenant l’URL ou le chemin vers l’image, et optionnellement un titre entouré par des guillemets droits simples ou doubles.

La syntaxe pour les images par référence ressemble à ceci :

![Texte alternatif][id] 

Où « id » est le nom de la référence de l’image. Les références sont définies en utilisant la même syntaxe que celle des liens par référence :

[id]: url/vers/image "Titre optionnel"

Au moment d’écrire ceci, Markdown n’a pas de syntaxe pour spécifier les dimensions d’une image ; si c’est important pour vous, vous n’avez qu’à utiliser la balise HTML <img alt="" />.

Divers

Liens automatiques

Markdown comprend dans sa syntaxe un raccourci permettant de créer des liens « automatiquement » pour les URLs et les adresses de courrier électronique : entourez tout simplement l’adresse par des chevrons. Ceci signifie que si vous voulez rendre visible l’URL ou l’adresse de courrier tout en lui permettant d’être cliquable, vous pouvez écrire ceci :

<http://exemple.com/>

Markdown produira ceci :

http://exemple.com/

Les liens automatiques pour les adresses de courrier électronique fonctionnent de la même façon, sauf que Markdown exécutera en plus un encodage aléatoire en entités décimales et hexadécimales pour rendre l’adresse plus difficile à lire par les robots qui voudraient vous spammer. Par exemple, Markdown convertira ceci :

<adresse@exemple.com>

en quelque chose ressemblant à ça :

adresse@
exemple.com

ce qui sera affiché par le navigateur comme un lien cliquable vers « adresse@exemple.com ». (Ce type d’encodage par entité peut tromper beaucoup de robots, mais pas tous. C’est mieux que rien, mais une adresse publiée de cette façon finira probablement par être spammée.)

Échappement par barre oblique inverse

Markdown vous permet d’utiliser une barre oblique inverse \ pour générer des caractères littéraux qui auraient autrement une autre signification dans la syntaxe de Markdown. Par exemple, si vous voulez entourer un mot avec des astérisques (sans créer de balise HTML <em>), ajoutez une barre oblique inverse devant l’astérisque, comme ceci :

*astérisques littéraux* 

Markdown permet d’échapper les caractères suivants :

\   barre oblique inverse
`   guillemet oblique (accent grave)
*   astérisque
_   trait souligné
{}  accolades
[]  crochets
()  parenthèses
#   croisillon (dièse)
+   plus
-   moins (tiret)
.   point
!   point d'exclamation

Remerciements

Merci à Michel Fortin pour sa première traduction de la syntaxe Markdown de John Gruber dont cet article est largement inspiré.