{"partition": "head_middle", "source_domain": "michelf.ca", "digest": "sha1:VZ7E2WTKPOYJ3XTI72UQEW2ASNMEY4MU", "path": "/lustre/fsn1/projects/rech/qgz/uzq54wg/processed_redpajama/base_processing/output/fr/2014-15/000_00019.parquet"}
PHP Markdown : Syntaxe
Ceci est une traduction de la syntaxe complète de Markdown, qui est détaillée en anglais sur la page Markdown Syntax de Daring Fireball. Les termes utilisés pour cette traduction sont énumérés dans le Lexique.
HTML intercalé
Échappement automatique des caractères spéciaux
Élément de bloc
Paragraphes et sauts de ligne
Blocs de citation
Blocs de code
Lignes horizontales
Élément de texte
Emphase
Échappement par barre oblique inverse
Liens automatiques
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.
À 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 avez déjà utilisé le courrier électronique.
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. Le 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 convoyé 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 <p> 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.
&lt;td&gt;Foo&lt;/td&gt;
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 <span>, <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 d’étendue de texte.
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 perluètes 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;.
La perluète est particulièrement désagréable pour ceux qui écrivent pour le web. Si vous voulez parler de « AT&T », vous devrez écrire « AT&amp;T ». Vous devrez aussi échapper les perluètes à l’intérieur des URLs. Cela signifie que si vous voulez créer un lien vers :
http://images.google.com/images?num=30&amp;q=larry+bird
vous devrez encoder l’URL comme suit :
http://images.google.com/images?num=30&amp;amp;q=larry+bird
dans l’attribut href de la balise <a>. Il n’est pas nécessaire de dire que c’est facile à oublier ; il s’agit probablement de la plus grande source d’erreur de validation HTML sur les sites web qui sont autrement valides.
Markdown vous permet d’utiliser ces caractères de façon naturelle en prenant soin de les encoder pour vous quand c’est nécessaire. Si vous utilisez une perluète pour débuter une entité HTML, elle restera inchangée ; autrement elle sera convertie en &amp;.
Alors, si vous voulez inclure le symbole de copyright dans votre article, vous pouvez écrire :
&amp;copy;
et Markdown n’y touchera pas. Mais si vous écrivez :
AT&amp;T
Markdown le convertira en :
AT&amp;amp;T
De la même façon, parce que Markdown supporte le HTML intercalé, si vous utilisez les chevrons pour délimiter les balises HTML, Markdown les traitera comme tel. Mais si vous écrivez :
4 &lt; 5
4 &amp;lt; 5
Cependant, à l’intérieur des blocs ou des étendues de code, les chevrons et les perluètes seront toujours encodés automatiquement. Ceci facilite grandement l’utilisation de Markdown quand il s’agit d’écrire au sujet du HTML. (Par opposition au HTML brut qui est un très mauvais format pour écrire à propos de sa propre syntaxe parce que chaque < et & dans vos exemples de code doivent être échappés.)
Éléments de bloc
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 <br />.
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 « retour ».
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