Syntaxe Markdown
Avouons-le : écrire du contenu pour le Web est fastidieux. Les éditeurs WYSIWYG aident à alléger cette tâche, mais ils se traduisent généralement par un code horrible, ou pire encore, des pages Web laides.
Markdown est une meilleure façon d'écrire du HTML, sans toutes les complexités et la laideur qui l'accompagnent habituellement.
Certains des principaux avantages sont :
- Markdown est simple à apprendre, avec un minimum de caractères supplémentaires, il est donc également plus rapide d'écrire du contenu.
- Moins de risques d'erreurs lors de l'écriture en markdown.
- Produit une sortie XHTML valide.
- Maintient le contenu et l'affichage visuel séparés, de sorte que vous ne pouvez pas gâcher l'apparence de votre site.
- Écrivez dans n'importe quel éditeur de texte ou application Markdown que vous aimez.
- Markdown est un plaisir à utiliser !
John Gruber, l'auteur de Markdown, le dit ainsi :
L'objectif primordial de la conception de la syntaxe de formatage de Markdown est de la rendre aussi lisible que possible. L'idée est qu'un document au format Markdown doit être publiable tel quel, en texte brut, sans donner l'impression qu'il a été conçu avec des balises ou des instructions de formatage. Alors que la syntaxe de Markdown a été influencée par plusieurs filtres texte-HTML existants, la principale source d'inspiration pour la syntaxe de Markdown est le format du courrier électronique en texte brut. --John Gruber
Grav est livré avec un support intégré pour Markdown et Markdown Extra. Vous devez activer Markdown Extra dans votre fichier de configuration system.yaml.
Sans plus tarder, passons en revue les principaux éléments de Markdown et à quoi ressemble le HTML résultant :
Titres
Les titres de h1 à h6 sont construits avec un # pour chaque niveau :
# h1 Titre
## h2 Titre
### h3 Titre
#### h4 Titre
##### h5 Titre
###### h6 Titre
donne :
h1 Titre
h2 Titre
h3 Titre
h4 Titre
h5 Titre
h6 Titre
HTML:
<h1>h1 Titre</h1>
<h2>h2 Titre</h2>
<h3>h3 Titre</h3>
<h4>h4 Titre</h4>
<h5>h5 Titre</h5>
<h6>h6 Titre</h6>
Commentaires
Les commentaires doivent être compatibles HTML
<!--
Ceci est un commentaire
-->
Le commentaire ne doit PAS être vu :
Lignes horizontales
L'élément HTML <hr> sert à créer une "rupture thématique" entre les éléments de niveau paragraphe. Dans Markdown, vous pouvez créer un <hr>avec l'un des éléments suivants :
___: trois traits de soulignement consécutifs---: trois tirets consécutifs***: trois astérisques consécutifs
correspondant à :
Corps du texte
Le corps du texte écrit normalement, le texte brut sera entouré de balises <p></p> dans le rendu HTML.
Donc, cette copie du corps :
Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. Et legere ocurreret pri, animal
tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis son ex, soluta officiis
concludaturque ei qui, vide sensibus vim ad.
donne cela en HTML :
<p>Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. Et legere ocurreret pri,
animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officis his ex, soluta
officiis concludaturque ei qui, vide sensibus vim ad.</p>
Un saut de ligne peut se faire avec 2 espaces suivis d'1 retour.
HTML en ligne
Si vous avez besoin d'une certaine balise HTML (avec une classe), vous pouvez simplement utiliser HTML :
Paragraphe dans Markdown.
<div class="classe">
Ceci est <b>HTML</b>
</div>
Paragraphe dans Markdown.
Rendus
Gras
Pour mettre en valeur un extrait de texte avec un poids de police plus lourd.
L'extrait de texte suivant est affiché en gras.
**rendra le texte en gras**
correspondant à :
rendra le texte en gras
et en HTML :
<strong>rendu en texte gras</strong>
Italique
Pour mettre en évidence un extrait de texte en italique.
L'extrait de texte suivant est rendu en italique.
_rendra le texte en italique_
correspondant à :
rendra le texte en italique
et en HTML :
<em>rendu sous forme de texte en italique</em>
Barré
Dans GFM (GitHub aromatisé Markdown), vous pouvez faire des barrés.
~~Barrez ce texte.~~
correspondant à :
Barrez ce texte.
et en HTML :
<del>Barrez ce texte.</del>
Blockquotes
Pour citer des blocs de contenu provenant d'une autre source dans votre document.
Ajoutez > avant tout texte que vous souhaitez citer.
> **Fusion Drive** combine un disque dur avec un stockage flash (disque SSD) et le présente comme un seul volume logique avec l'espace des deux disques combinés.
Correspond à :
et en HTML :
<blockquote>
<p><strong>Fusion Drive</strong> combine un disque dur avec un stockage flash
(disque SSD) et le présente comme un volume logique unique avec l'espace des
deux disques combinés.</p>
</blockquote>
Les blocs de citations peuvent également être imbriqués :
> Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue.
Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.
>> Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor
odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.
Correspond à :
Notices
>>>) est obsolète. Les avis sont désormais gérés via un plugin dédié appelé Markdown Notices.
Listes
Non ordonnées
Une liste d'éléments dans laquelle l'ordre des éléments n'a pas d'importance explicite.
Vous pouvez utiliser l'un des symboles suivants pour désigner les puces de chaque élément de la liste :
* puce valide
- puce valide
+ puce valide
Par exemple
+ Lorem ipsum dolor sit amet
+ Consectetur adipiscing élite
+ Integer molestie lorem at massa
+ Facilisis in pretium nisl aliquet
+ Nulla volutpat aliquam velit
- Phasellus iaculis nèque
- Ultricies de Purus sodales
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat à
+ Faucibus porta lacus fringilla vel
+ Aenean sit amet erat nunc
+ Eget porttitor lorem
Correspond à :
- Lorem ipsum dolor sit amet
- Consectetur adipiscing élite
- Integer molestie lorem at massa
- Facilisis in pretium nisl aliquet
- Nulla volutpat aliquam velit
- Phasellus iaculis neque
- Purus sodales ultricies
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat at
- Faucibus porta lacus fringilla vel
- Aenean sit amet erat nunc
- Eget porttitor lorem
Et en HTML
<ul>
<li>Lorem ipsum dolor sit amet</li>
<li>Consectetur adipiscing elit</li>
<li>Entier molestie lorem at massa</li>
<li>Facilisis in pretium nisl aliquet</li>
<li>Nulla volutpat aliquam velit
<ul>
<li>Phasellus iaculis nèque</li>
<li>Ultricies de Purus sodales</li>
<li>Vestibulum laoreet porttitor sem</li>
<li>Ac tristique libero volutpat at</li>
</ul>
</li>
<li>Faucibus porta lacus fringilla vel</li>
<li>Énée sit amet erat nunc</li>
<li>Eget porttitor lorem</li>
</ul>
Ordonnées
Une liste d'éléments dans lesquels l'ordre des éléments importe explicitement.
1. Lorem ipsum dolor sit amet
2. Consectetur adipiscing elit
3. Integer molestie lorem at massa
4. Facilisis in pretium nisl aliquet
5. Nulla volutpat aliquam velit
6. Faucibus porta lacus fringilla vel
7. Aenean sit amet erat nunc
8. Eget porttitor lorem
Correspond à :
- Lorem ipsum dolor sit amet
- Consectetur adipiscing elit
- Integer molestie lorem at massa
- Facilisis in pretium nisl aliquet
- Nulla volutpat aliquam velit
- Faucibus porta lacus fringilla vel
- Aenean sit amet erat nunc
- Eget porttitor lorem
Et en HTML :
<ol>
<li>Lorem ipsum dolor sit amet</li>
<li>Consectetur adipiscing elit</li>
<li>Entier molestie lorem at massa</li>
<li>Facilisis in pretium nisl aliquet</li>
<li>Nulla volutpat aliquam velit</li>
<li>Faucibus porta lacus fringilla vel</li>
<li>Énée sit amet erat nunc</li>
<li>Eget porttitor lorem</li>
</ol>
ASTUCE : Si vous n'utilisez que 1. pour chaque numéro, Markdown numérotera automatiquement chaque élément. Par exemple:
1. Lorem ipsum dolor sit amet
1. Consectetur adipiscing elit
1. Integer molestie lorem at massa
1. Facilisis in pretium nisl aliquet
1. Nulla volutpat aliquam velit
1. Faucibus porta lacus fringilla vel
1. Aenean sit amet erat nunc
1. Eget porttitor lorem
Correspond à :
- Lorem ipsum dolor sit amet
- Consectetur adipiscing elit
- Integer molestie lorem at massa
- Facilisis in pretium nisl aliquet
- Nulla volutpat aliquam velit
- Faucibus porta lacus fringilla vel
- Aenean sit amet erat nunc
- Eget porttitor lorem
Code
Code en ligne
Enveloppez les extraits de code en ligne avec `.
Dans cet exemple, `<section></section>` doit être enveloppé comme **code**.
Correspond à :
Dans cet exemple, <section></section> doit être enveloppé de code.
et en HTML :
<p>Dans cet exemple, <code><section></section></code> doit être entouré de <strong>code</strong>.</p>
Code indenté
Ou indentez plusieurs lignes de code d'au moins quatre espaces, comme dans :
// Du commentaire
ligne 1 du code
ligne 2 du code
ligne 3 du code
Ce qui rendra :
// Certains commentaires
ligne 1 du code
ligne 2 du code
ligne 3 du code
Et en HTML :
<pre>
<code>
// Certains commentaires
ligne 1 du code
ligne 2 du code
ligne 3 du code
</code>
</pre>
Code de bloc "fences"
Utilisez "fences" ``` pour bloquer plusieurs lignes de code avec un attribut de langue.
```
Exemple de texte ici...
```
Et en HTML :
<pre language-html>
<code>Exemple de texte ici...</code>
</pre>
Mise en évidence de la syntaxe
GFM, ou "GitHub Flavored Markdown" prend également en charge la coloration syntaxique. Pour l'activer, ajoutez simplement l'extension de fichier du langage que vous souhaitez utiliser directement après le premier code "fence", ```js, et la coloration syntaxique sera automatiquement appliquée dans le rendu HTML. Par exemple, pour appliquer la coloration syntaxique au code JavaScript :
```js
grunt.initConfig({
assemble: {
options: {
assets: 'docs/assets',
data: 'src/data/*.{json,yml}',
helpers: 'src/custom-helpers.js',
partials: ['src/partials/**/*.{hbs,md}']
},
pages: {
options: {
layout: 'default.hbs'
},
files: {
'./': ['src/templates/pages/index.hbs']
}
}
}
};
```
Correspond à :
grunt.initConfig({
assemble: {
options: {
assets: 'docs/assets',
data: 'src/data/*.{json,yml}',
helpers: 'src/custom-helpers.js',
partials: ['src/partials/**/*.{hbs,md}']
},
pages: {
options: {
layout: 'default.hbs'
},
files: {
'./': ['src/templates/pages/index.hbs']
}
}
}
};
Les tableaux
Les tableaux sont créés en ajoutant des barres comme séparateurs entre chaque cellule et en ajoutant une ligne de tirets (également séparés par des barres) sous l'en-tête. Notez que les pipes n'ont pas besoin d'être alignés verticalement.
| Option | Description |
| ------ | ----------- |
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
Correspond à :
| Option | Description |
|---|---|
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
Et en HTML :
<tableau>
<tête>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>données</td>
<td>chemin d'accès aux fichiers de données pour fournir les données qui seront transmises aux modèles.</td>
</tr>
<tr>
<td>moteur</td>
<td>moteur à utiliser pour le traitement des modèles. Le guidon est la valeur par défaut.</td>
</tr>
<tr>
<td>ext</td>
<td>extension à utiliser pour les fichiers dest.</td>
</tr>
</tbody>
</table>
Texte aligné à droite
L'ajout de deux-points sur le côté droit des tirets sous n'importe quel titre alignera à droite le texte de cette colonne.
| Option | Description |
| ------:| -----------:|
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
| Option | Description |
|---|---|
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
Liens
Lien de base
[Assemble] (https://assemble.io)
Rend (survolez le lien, il n'y a pas d'info-bulle):
Et en HTML :
<a href="https://assemble.io">Assembler</a>
Ajouter un titre
[Upstage](https://github.com/upstage/ "Visitez Upstage!")
Rend (passez la souris sur le lien, il devrait y avoir une info-bulle):
En HTML :
<a href="https://github.com/upstage/" title="Visitez Upstage!">Upstage</a>
Ancres nommées
Les ancres nommées vous permettent d'accéder au point d'ancrage spécifié sur la même page. Par exemple, chacun de ces chapitres :
# Table des matières
* [Chapitre 1](#chapitre-1)
* [Chapitre 2](#chapitre-2)
* [Chapitre 3](#chapitre-3)
passera à ces sections :
## Chapitre 1 <a id="chapter-1"></a>
Contenu du premier chapitre.
## Chapitre 2 <a id="chapter-2"></a>
Contenu du premier chapitre.
## Chapitre 3 <a id="chapter-3"></a>
Contenu du premier chapitre.
REMARQUE que le placement spécifique de la balise d'ancrage semble être arbitraire. Ils sont placés en ligne ici car cela semble être discret et cela fonctionne.
Images
Les images ont une syntaxe similaire aux liens mais incluent un point d'exclamation précédent.
ou alors:
Comme les liens, les images ont également une syntaxe de style note de bas de page :
![Alt text][id]
Avec une référence plus loin dans le document définissant l'emplacement de l'URL :
[id] : https://octodex.github.com/images/dojocat.jpg "Le Dojocat"