PHP Markdown Extra
PHP Markdown Extra est une version spéciale de PHP Markdown comprenant des options qui ne sont pas disponibles présentement dans la syntaxe Markdown. Vous pouvez télécharger PHP Markdown Extra à partir de la page d’accueil de PHP Markdown.
Ce document explique les changement et les ajouts à la syntaxe Markdown appliqués à PHP Markdown Extra. Vous devrez être déjà familier avec la documentation originale de la syntaxe Markdown avant de lire ce document.
- HTML intercalé
- Markdown dans un bloc HTML
- Attribut « id » pour les titres
- Blocs de code balisés
- Tableaux
- Listes de définitions
- Notes de bas de page
- Abréviations
- Emphase
- Échappement par barre oblique inverse
HTML intercalé
Avec Markdown vous pouvez insérer des balises HTML au milieu de votre texte. C’est souvent pratique quand vous avez besoins d’éléments qui ne sont pas accessibles par la syntaxe Markdown mais qui sont facile à écrire en HTML.
Mais Markdown possède impose un restriction sévère quand au HTML que l’on introduit. Tiré de la documentation sur la syntaxe :
Les élément 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és avec des tabulations ou des espaces.
Ces restrictions sont levés avec PHP Markdown Extra et sont remplacés par deux autres moins restrictives :
La balise d’ouverture d’un élément bloc ne doit pas être indenté par plus de trois espaces. Toute balise indenté de plus de trois espaces sera traité en bloc de code tel que défini par la syntaxe normale de Markdown.
Quand l’élément bloc se trouve à l’intérieur d’une liste, tout son contenu doit être indenté au même niveau que l’élément de la liste. (Plus d’indentation ne causera aucun problème en autant que la première balise ouvrante n’est pas suffisamment indenté pour devenir un bloc de code — voir la première règle.)
Markdown dans un bloc HTML
Précédemment avec Markdown, vous ne pouviez pas include du texte formaté pour Markdown dans un élément <div>. Parce que <div> est un élément bloc, Markdown ne formate pas son contenu.
PHP Markdown Extra vous donne un moyen de placer du texte formaté pour Markdown dans des éléments bloc. Vous faites cela en ajoutant l’attribut markdown à la balise avec la valeur 1, ce qui donne markdown="1" comme ici :
<div markdown="1">
Voici du *vrai* texte Markdown.
</div>
L’attribut markdown="1" sera enlevé et le contenu du <div> sera converti en HTML. Le résultat final sera :
<div>
<p>Voici du <em>vrai</em> texte Markdown.</p>
</div>
PHP Markdown Extra est suffisamment intelligent pour appliquer le formatage correctement dépendant de l’élément bloc sur lequel vous placez l’attribut markdown. Si vous appliquez l’attribut markdown sur un élément <p> par exemple, seul les éléments de niveau texte seront produits à l’intérieur — les listes, les blocs de citation et les blocs de code ne seront pas permis.
Il y a cependant quelque cas qui sont ambigus, en voici justement un :
<table>
<tr>
<td markdown="1">Voici du *vrai* texte Markdown.</td>
</tr>
</table>
Une cellule de tableau peut contenir soit des éléments bloc ou directement du texte. Dans un cas comme celui-ci, PHP Markdown Extra produira uniquement les éléments de niveau texte. Si vous voulez permettre les blocs, écrivez markdown="block".
Attribut « id » pour les titres
Avec PHP Markdown Extra, vous pouvez donner un attribut « id » à vos titres. Vous devez ajouter l’identifiant précédé d’un dièse entre accolades à la fin de la ligne du titre, comme ceci :
Titre 1 {#titre1}
=======
## Titre 2 ## {#titre2}
Ceci permet de créer des liens aux différentes parties du document de cette façon :
[Lien vers le titre 1](#titre1)
Il n’est possible de spécifier l’attribut « id » que pour les titres présentement.
Blocs de code balisés
La version 1.2 de PHP Markdown Extra ajoute une syntaxe pour les blocs de code sans indentation. Les blocs de code balisés sont tout comme les blocs de code de Markdown, à l’exception qu’ils n’ont pas d’indentation et utilisent à la place une ligne balise au début et à la fin pour délimiter le bloc de code. Le bloc de code débute avec une ligne constituée de trois tilde ~ ou plus, et se termine à la première ligne contenant le même nombre de tilde ~. Par exemple :
Voici un paragraphe introduisant:
~~~~~~~~~~~~~~~~~~~~~~~~~~~
un bloc de code d'une ligne
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Contrairement à leur équivalent avec indentation, les blocs de code balisés peuvent débuter et se terminer avec des lignes vierges :
~~~
ligne vierge avant
ligne vierge après
~~~
Les blocs de code avec indentation ne peuvent pas être utilisés immédiatement après une liste parce que l’indentation de la liste prend préséance, mais vous pouvez utiliser un bloc de code balisé à la place :
1. Élément d'une liste
Pas un code de bloc indenté, mais un second
paragraphe dans l'élément de la liste
~~~
Ceci est un bloc de code balisé
~~~
Les blocs de code balisés sont aussi idéaux si vous devez copier-coller du code dans un éditeur qui ne supporte pas l’indentation automatique, tel une boîte de texte dans votre navigateur web.
Tableaux
PHP Markdown Extra possède sa propre syntaxe pour écrire des tableaux simples. Un tableau « simple » ressemble à ceci :
Premier titre | Second titre
------------- | ------------
Cellule | Cellule
Cellule | Cellule
La première ligne contient le titre des colones ; la deuxième ligne contient une ligne de séparation obligatoire entre les titres et les autres cellules ; chaque ligne qui suit représente une rangé du tableau. Les colones sont séparés par le caractère ligne verticale (|). Une fois converti en HTML, le résultat est le suivant :
<table>
<thead>
<tr>
<th>Premier titre</th>
<th>Second titre</th>
</tr>
</thead>
<tbody>
<tr>
<td>Cellule</td>
<td>Cellule</td>
</tr>
<tr>
<td>Cellule</td>
<td>Cellule</td>
</tr>
</tbody>
</table>
Si vous voulez, vous pouvez ajouter une ligne verticale supplémentaire au début et à la fin de chaque ligne du tableau. Pour illustrer, ceci donnera la même résultat que le tableau précédent :
| Premier titre | Second titre |
| ------------- | ------------ |
| Cellule | Cellule |
| Cellule | Cellule |
Note : Un tableau doit avoir au minimum une ligne verticale sur chaque ligne pour que PHP Markdown Extra le lise correctement. Ceci veux dire que la seule façon de créer un tableau à une seule colonne est d’ajouter une ligne verticale au début ou à la fin (ou les deux) de chaque ligne.
Vous pouvez spécifier un alignement pour chaque colonne en ajoutant des deux-points à la ligne de séparation. Un deux-point à gauche de la ligne signifie que la colonne doit être aligné sur la gauche ; un deux-point à droite signifie un alignement à droite ; des deux-points de chaque côté signifie que la colonne est centrée.
| Article | Valeur |
| ---------- | ------:|
| Ordinateur | 1600 $ |
| Téléphone | 12 $ |
| Tuyau | 1 $ |
L’attribut HTML align est appliqué à chaque cellule de la colonne concernée.
Vous pouvez appliquer du formatage de niveau texte à chaque cellule en utilisant la syntaxe Markdown :
| Nom de fonction | Description |
| --------------- | ------------------------------ |
| `aide()` | Affiche la fenêtre d'aide. |
| `exploser()` | **Détruit l'ordinateur !** |
Listes de définitions
PHP Markdown Extra ajouter les listes de définitions. Une liste de définition est composé de termes et de la définition de ces termes, un peu comme dans un dictionnaire.
Une liste de définition simple pour PHP Markdown Extra est composé d’une ligne contenant un terme suivit par un deux-point et la définition pour le terme.
Pomme
: Fruit charnu, de forme quasi sphérique, déprimée au
sommet et à la base, à pulpe homogène.
Orange
: Fruit de l'oranger, arbre de la famille des Rutacées.
Chaque terme doit être séparé de la définition qui le précède par une ligne blanche. Les définitions peuvent s’étaler sur plusieurs lignes. Dans un tel cas, les lignes devrait être indentées, mais ce n’est pas vraiment nécessaire : si vous êtes paresseux, vous pouvez oublier d’indenter une définition qui s’étale sur plusieurs lignes et ça fonctionnera toujours :
Pomme
: Fruit charnu, de forme quasi sphérique, déprimée au
sommet et à la base, à pulpe homogène.
Orange
: Fruit de l'oranger, arbre de la famille des Rutacées.
Les deux listes de définitions précédentes donne le même résultat en HTML :
<dl>
<dt>Apple</dt>
<dd>Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.</dd>
<dt>Orange</dt>
<dd>The fruit of an evergreen tree of the genus Citrus.</dd>
</dl>
Les deux-points en tant que marqueur d’une définition sont généralement accotés sur la marge de gauche, mais peuvent être indentés par un, deux ou trois espaces. Les marqueurs de définition doivent êtres suivi d’au moins un espace ou d’une tabulation.
Les termes d’une listes de définition peuvent avoir plus d’une définition associée :
Pomme
: Fruit charnu, de forme quasi sphérique, déprimée au
sommet et à la base, à pulpe homogène.
: Une compagnie d'ordinateur américaine.
Orange
: Fruit de l'oranger, arbre de la famille des Rutacées.
Vous pouvez aussi associer plusieurs termes à la même définition :
Terme 1
Terme 2
: Définition a
Terme 3
: Définition b
Si une définition est précédé par une ligne blanche, PHP Markdown Extra l’enrobera dans une balise <p> dans la sortie HTML. Par exemple, ceci :
Pomme
: Fruit charnu, de forme quasi sphérique, déprimée au
sommet et à la base, à pulpe homogène.
Orange
: Fruit de l'oranger, arbre de la famille des Rutacées.
produira cela :
<dl>
<dt>Pomme</dt>
<dd>
<p>Fruit charnu, de forme quasi sphérique, déprimée au
sommet et à la base, à pulpe homogène.</p>
</dd>
<dt>Orange</dt>
<dd>
<p>Fruit de l'oranger, arbre de la famille des Rutacées.</p>
</dd>
</dl>
Et tout comme pour les éléments d’une liste ordonnée ou non-ordonnée, une définition peut contenir plusieurs paragraphes et inclure d’autre éléments bloc tel que des blocs de citation, des blocs de code, des listes et même d’autre listes de définition.
Terme 1
: Voici une définition 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.
: Une deuxième définition pour le terme 1, aussi enrobé d'un
paragraphe dû à la ligne blanche qui précède.
Terme 2
: Cette définition possède un bloc de code, un bloc de citation
et une liste.
bloc de code.
> bloc de citation
> sur deux lignes.
1. premier élément d'une liste
2. deuxième élément d'une liste
Notes de bas de page
Les notes de bas de page fonctionnent de la même façon que les liens par référence. Une note de bas de page comprend deux choses : un marqueur dans le texte qui deviendra un nombre surélevé ; une définition de note de bas de page qui sera placé dans une liste comprendant toutes les notes à la fin du document. Une note de bas de page ressemble à ceci :
Un peu de texte avec une note de bas de page.[^1]
[^1]: Et voici la note.
Les défintitions de notes de bas de page peuvent se trouver n’importe où dans le document, mais les notes seront toujours listés dans l’ordre où elle sont référencé dans le texte. Notez qu’il est impossible de faire deux liens vers la même note : si vous essayez, la deuxième référence restera sous forme de texte.
Chaque note doit avoir un nom distinct. Le nom sera utilisé pour lier la référence de note à son texte, mais n’aura pas d’effet sur la numérotation. Les noms peuvent contenir n’importe quel caractère valide dans l’attribut id du HTML.
Les notes de bas de page peuvent contenir des éléments de type bloc, ce qui permet d’y mettre plusieurs paragrahes, listes, blocs de citation et ainsi de suite dans une note. Cela fonctionne de la même façon que pour les items d’une liste : vous n’avez qu’à indenter les paragraphes qui suivent par quatre espace dans la définition de la note de bas de page :
Un peu de texte avec une note de bas de page.[^1]
[^1]: Et voici la note.
Et voilà un deuxième paragraphe.
Si vous voulez que les choses soit mieux alignées, vous pouvez laisser la première ligne de la note vide et commencer le premier paragraph juste au dessous :
[^1]:
Et voici la note.
Et voilà un deuxième paragraphe.
Sortie
Un seul format de sortie HTML ne pourra vraisemblablement pas satisfaire tout le monde. Une future version pourrait fournir une interface de programmation permettant de redéfinir le format. Mais pour l’instant, la sortie est calqué sur le modèle de Daring Fireball, avec quelques petites modifications. Voici la sortie par défaut du premier exemple mentioné plus haut :
<p>Un peu de texte avec une note de bas de page.
<sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup></p>
<div class="footnotes">
<hr />
<ol>
<li id="fn:1">
<p>Et voici la note.
<a href="#fnref:1" rev="footnote">↩</a></p>
</li>
</ol>
</div>
Un peu compliqué, mais dans un navigatueur le résultat ressemble à ça :
Les attributs rel et rev sur les liens exprime la relation qu’ils ont avec les éléments auxuels ils sont liés. Les liens des références se rendent aux notes (donc rel="footnote") et, à l’inverse, les liens de retour partent des notes (donc rev="footnote"). On peut utiliser ces attributs pour appliquer un style aux liens avec les règles suivantes :
a[rel="footnote"]
a[rev="footnote"]
Vous pouvez aussi personalliser les attributs class et title pour les liens des marqueurs et les liens de retour. Il y a quatre règlages configurables au début du fichier. À l’intérieur de ces attributs, toute occurence de %% sera remplacé par le numéro de la note courante. Par exemple, vous pourriez utiliser :
define( 'MARKDOWN_FN_LINK_TITLE', "Aller à la note %%." );
Abréviations
PHP Markdown Extra ajoute un support pour les abréviations (La balise HTML <abbr>). Ça fonctionne d’une façon très simple. On définie une abbréviation comme ceci :
*[HTML]: Hyper Text Markup Language
*[ONU]: Organisation des nations unies
et, ailleurs dans le document, on écrit du texte tout à fait normalement :
La spécification HTML
n'a rien à voir avec l'ONU.
et toutes les occurences des termes définis comme abbréviation deviendront :
La spécification <abbr title="Hyper Text Markup Language">HTML</abbr>
n'a rien à voir avec l'<abbr title="Organisation des nations unies">ONU</abbr>.
Les abbréviations sont sensibles à la casse, elle peuvent aussi s’étendre sur plusieurs mots si définies comme telle. Une abbréviation peut aussi avoir une définition vide, dans un quel cas la balise <abbr> sera ajoutée dans le texte mais l’attribut title sera omis.
L'opération Tigra Genesis avance bien.
*[Tigra Genesis]:
Les définitions d’abbréviations peuvent se trouver n’importe où dans le document. Elle sont retiré du document final.
Emphase
Les règles de l’emphase on légèrement changées par rapport à la syntaxe originale de Markdown. Avec PHP Markdown Extra, les traits soulignés au milieu d’un mot sont maintenant traités en tant que caractères littéraux. L’emphase par les traits de soulignement ne fonctionne que pour les mots entiers. Si vous voulez placer en emphase seulement une partie d’un mot, c’est toujours possible en utilisant les astérisques comme marqueurs d’emphase.
Par exemple, avec ceci :
Veuillez ouvrir le dossier "boîte_magique_secrète".
PHP Markdown Extra ne convertira pas les traits soulignés en emphase parce qu’ils sont au milieu d’un mot. Le résultat HTML de PHP Markdown Extra est le suivant :
<p>Veuillez ouvrir le dossier "boîte_magique_secrète".</p>
L’emphase avec les traits soulignés fonctionne toujours en autant que vous placiez des mots entiers en emphase, comme ceci :
J'aime ça quand tu me dit _je t'aime_.
La même chose s’applique pour l’emphase forte : avec PHP Markdown Extra, vous ne pouvez plus placer d’emphase forte au milieu d’un mot en utilisant des traits de soulignement, il est nécessaire d’utiliser des astérisques comme marqueur d’emphase.
Échappement par barre oblique inverse
PHP Markdown Extra ajoute le deux-points (:) et la ligne verticale (|) à la listes des caractères qu’il est possible d’échapper avec une barre oblique inverse. Ceci permet d’éviter que ces caractères forment une liste de définitions ou un tableau.
Remerciements
Plusieurs idées implantés ici ont été discutées auparavant sur la liste Markdown Discuss. J’aimerais remercier tout ceux qui ont participé à la discussion et proposé des solutions et des améliorations à la syntaxe Markdown.