Principaux usages de la syntaxe Markdown
Markdown est une syntaxe simplifiée qui permet d'utiliser quelques touches du clavier alphanumérique pour définir un certain nombre de paramètres de présentation qui nécessiteraient sinon l'usage de balises HTML...
Les liens
Pour les liens, la syntaxe est relativement simple :
[Lien vers Google](http://www.google.com "Google")
Ce qui génèrera le HTML suivant :
<a href="http://www.google.com" title="Google">Lien vers Google</a>
Le titre est bien évidemment optionnel.
Les titres
Pour les titres, on a plusieurs choix :
Titre de niveau 1
=================
# Une autre manière d'écrire un titre de niveau 1
Titre de niveau 2
-
###### Titre de niveau 6
### On peut remettre des dièses derrière pour l'esthétique si on veut ###
Cela génèrera ceci :
<h1>Titre de niveau 1</h1>
<h1>Une autre manière d'écrire un titre de niveau 1</h1>
<h2>Titre de niveau 2</h2>
<h6>Titre de niveau 6</h6>
<h3>On peut remettre des dièses derrière pour l'esthétique si on veut</h3>
Mettre du texte en valeur
Pour mettre du texte en valeur, rien de plus simple :
Voici du texte *important* et **très important**
Voici une _autre_ syntaxe pour la __même chose__
Ce qui donne :
<p>Voici du texte <em>important</em> et <strong>très important</strong></p>
<p>Voici une <em>autre</em> syntaxe pour la <strong>même chose</strong></p>
Insertion de code
Pour insérer du code, il y a plusieurs moyens :
Ceci est du `code au milieu d'une ligne`
bloc de code
suite du bloc de code
Ce qui va générer ceci :
<p>Ceci est du <code>code au milieu d'une ligne</code></p>
<pre><code>bloc de code
suite du bloc de code</code></pre>
Pour la seconde manière d'insérer du code, il faut indenter chaque ligne de 4 espaces (ou un tab, au choix).
Les citations
Pour insérer des citations, c'est également très facile. Voici à quoi ça ressemble :
> Paragraphe 1 de la citation.
> Suite du paragraphe.
> Paragraphe 2 (même citation)
Voici le HTML généré :
<blockquote>
<p>Paragraphe 1 de la citation. Suite du paragraphe.</p>
<p>Paragraphe 2 (même citation)</p>
</blockquote>
Ajouts spécifiques à PHP Markdown Extra
Notes de bas de page
Pour les notes de bas de page, rien de plus simple. Il suffit de mettre ceci à l'endroit où vous voulez faire apparaître la note :
Texte à annoter[^1]
Et puis de la définir n'importe où dans le document de la manière suivante :
[^1]: Note de bas de page
Il ajoutera automatiquement ceci à l'endroit à annoter :
<sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup>
Et placera ceci tout en bas du document :
<div class="footnotes">
<hr/>
<ol>
<li id="fn:1">
<p>Note de bas de page<a href="#fnref:1" rev="footnote">↩</a></p></li>
</ol>
</div>
Comme vous pouvez le voir, vous pouvez alors cliquer sur le chiffre pour aller à la note de bas de page et puis cliquer sur la flèche retour pour revenir à l'endroit de la note dans le texte (le ↩ représente ceci : ↩). Rien de plus pratique !
Les tableaux
PHP Markdown Extra vous propose aussi un moyen sympa pour faire des tableaux. Ça ressemble à ça :
Titre 1 | Titre 2 | Titre 3 | Titre 4
--- | :-- | :-: | --:
gauche | gauche | centré | droite
ligne 2 | ligne2 | ligne2 | ligne2
Ce qui produira le code suivant :
<table>
<thead>
<tr>
<th>Titre 1 </th>
<th align="left"> Titre 2 </th>
<th align="center"> Titre 3 </th>
<th align="right"> Titre 4</th>
</tr>
</thead>
<tbody>
<tr>
<td>gauche </td>
<td align="left"> gauche </td>
<td align="center"> centré </td>
<td align="right"> droite</td>
</tr>
<tr>
<td>ligne 2 </td>
<td align="left"> ligne2 </td>
<td align="center"> ligne2 </td>
<td align="right"> ligne2</td>
</tr>
</tbody>
</table>
L'alignement des cellules est déterminé via l'alignement du deux-points dans la ligne séparant le titre de la colonne associée (centré s'il est des deux cotés, à gauche s'il est à gauche ou absent et à droite s'il est... à droite).
Syntaxe additionnelle pour les blocs de code
PHP Markdown vous permet aussi une autre syntaxe pour les blocs de code qui est la suivante :
~~~
autre moyen pour un bloc de code
suite du bloc
~~~
Possibilité d'utiliser du Markdown à l'intérieur de blocs HTML
Normalement, Markdown ne traitera pas tout ce qui se trouve à l'intérieur d'élements représentant des blocs de texte (<pre>, <div>, <table>, <p>, etc.). Avec PHP Markdown Extra, il suffit d'ajouter l'attribut markdown=1 pour que l'intérieur du bloc soit traité, comme suit :
<div markdown=1>
Texte en **Markdown**
</div>
Le markdown=1 sera automatiquement enlevé, générant alors ceci :
<div>
<p>Texte en <strong>Markdown</strong></p>
</div>
Possibilité d'ajouter un ID et/ou une ou plusieurs classes aux titres
PHP Markdown Extra nous permet d'assigner un ID et/ou une ou plusieurs classes aux titres. Il suffit de les mettre derrière le titre entre accolades, comme suit :
# Titre avec un ID et deux classes {#id .classe .autreclasse}
Ce qui génèrera donc ceci :
<h1 id="id" class="classe autreclasse">Titre avec un ID et deux classes</h1>
On peut utiliser la même méthode pour des blocs de code (seulement avec la méthode des tildes), comme suit :
~~~~~ {#id .classe}
code
~~~~~
Définitions
On peut aussi créer des listes de définitions grâce à PHP Markdown Extra. La syntaxe est la suivante : le terme à définir, suivi d'un deux-points à la ligne, suivi de la définition. Exemple :
Site web
: Un site ou site web est un ensemble de pages web hyperliées entre elles et accessible à une adresse web.
Pomme
: La pomme est l'un des fruits les plus consommés dans le monde. Produite par le pommier, elle est comestible et a un goût sucré ou acidulé selon les variétés.
Ce qui générera ceci :
<dl>
<dt>Site web</dt>
<dd>Un site ou site web est un ensemble de pages web hyperliées entre elles et accessible à une adresse web.</dd>
<dt>Pomme</dt>
<dd>La pomme est l'un des fruits les plus consommés dans le monde. Produite par le pommier, elle est comestible et a un goût sucré ou acidulé selon les variétés.</dd>
</dl>
Abréviations
Dernière chose ajoutée par PHP Markdown Extra, les abréviations. On les définit comme suit :
*[HTML]: HyperText Markup Language
Ensuite, dès qu'on utilise le terme défini comme abréviation, il est automatiquement remplacé par ceci :
<abbr title="Hyper Text Markup Language">HTML</abbr>
Exemple :
*[HTML]: HyperText Markup Language
Le HTML est un langage relativement facile.
Deviendra :
<p>Le <abbr title="HyperText Markup Language">HTML</abbr> est un langage relativement facile.</p>