Rédiger en Markdown
Markdown est un outil de conversion de texte vers HTML pour la rédaction sur le web. Il permet de rédiger le texte dans un format facile à lire et à écrire, puis de le convertir en XHTML (ou HTML) valide.
L'idée n'est pas de créer une syntaxe permettant d'insérer plus facilement les balises HTML. HTML est un format de publication, Markdown est un format de rédaction.
Markdown permet donc de mettre en forme simplement du texte brut et de manière intelligible. Contrairement au HTML et ses balises, on comprend aisément un document formaté en Markdown.
C'est simple, clair et rapide pour rédiger un document à publier sur le web. On ne peut pas tout faire avec Markdown mais ça permet de rédiger un contenu complet et structuré (mais on peut mélanger Markdown et HTML sans problème).
L'autre avantage est de privilégier le contenu sans se préoccuper de la mise en forme.
L'utilisation de Markdown est recommandé pour écrire des courriels en texte brut.
Voici donc un petit memo pour utiliser Markdown (j'ai volontairement simplifié certains aspects que l'on peut retrouver dans les liens).
Sommaire
Les outils pour rédiger en Markdown
Pour rédiger simplement en Markdown et visualiser en temps réel son contenu, on peut utiliser Geany et son extension Markdown. Pour convertir en HTML on installe simplement le paquet Markdown.
apt-get install geany geany-plugin-markdown markdown
On démarre Geany depuis le menu: Développement > Geany
ou directement depuis le terminal:
geany &
Il faut d'abord activer l'extension dans Geany. Dans le menu: Outils > Gestionnaire de plugin. Ensuite, activer l'extension Markdown. Il est possible de modifier les préférences d'affichage.
Au cours de la rédaction, on pré-visualise le contenu dans l'onglet Aperçu Markdown.
Les fichiers Markdown portent l'extension .md ou .markdown.
Le nombre d'espace, l'ajout d'une ligne vide ou un caractère spécial peut empêcher le bon fonctionnement de la conversion vers HTML.
La syntaxe Markdown
On va voir la syntaxe utilisée par Markdown et tout ce qu'il est possible de faire avec. J'ai simplifié certains éléments et il est parfois possible d'utiliser plusieurs syntaxes différentes.
La gestion des titres
Pour mettre en forme un texte, on commence par ajouter des titres pour structurer son texte. Le symbole # permet de définir les niveaux de titres. Le titre de niveau 1 (considéré comme le plus élevé) doit être précédé de #. D'une manière générale, on ajoute autant de # que le niveau du titre voulu.
# Titre de niveau 1
## Titre de niveau 2
### Titre de niveau 3
#### Titre de niveau 4
<h1>Titre de niveau 1</h1>
<h2>Titre de niveau 2</h2>
<h3>Titre de niveau 3</h3>
<h4>Titre de niveau 4</h4>
Le rendu final:
Titre de niveau 1
Titre de niveau 2
Titre de niveau 3
Titre de niveau 4
La gestion des listes
On peut également ajouter des listes ordonnées (comme la liste des distributions GNU/Linux à tester) ou non ordonnées (comme la liste des OS à ne pas utiliser).
Pour les listes non ordonnées, on utilise * suivi d'un espace.
* HTML
* CSS
* PHP
* ...
<ul>
<li>HTML</li>
<li>CSS</li>
<li>PHP</li>
<li>...</li>
</ul>
Le rendu final:
- HTML
- CSS
- PHP
- ...
Pour les listes non ordonnées, on utilise un nombre suivi d'un point (ex: 1.).
1. Premier
2. Deuxième
3. Troisième
<ol>
<li>Premier</li>
<li>Deuxième</li>
<li>Troisième</li>
</ol>
Le rendu final:
- Premier
- Deuxième
- Troisième
La gestion des liens
Il n'est pas rare de faire référence à différents sites. Pour générer des liens, on a besoin de trois éléments.
Un élément qui sera le texte affiché (ex: nIQnutn), un autre qui sera l'URL (ex: http://blog.niqnutn.com) et optionnellement une description (affiché dans l'info-bulle au survol du lien).
[nIQnutn](http://blog.niqnutn.com/ "nIQnutn's blog")
<a href="http://blog.niqnutn.com/" title="nIQnutn's blog">nIQnutn</a>
Le rendu final:
On peut aussi l'utiliser pour faire des références internes (comme des sommaires, retour vers le haut de la page, etc.) ou utiliser les chemins relatifs pour accéder à une ressource sur le même serveur.
Retour vers le [Haut de page](#top "Top") ou se voir les [Actualités](/index.php?static5).
<p>Retour vers le <a href="#top" title="Top">Haut de page</a> ou voir les <a href="/index.php?static5">Actualités</a>.</p>
Le rendu final:
Retour vers le Haut de page ou voir les Actualités.
Encore plus simple, il est possible de créer des liens automatiquement à partir d'URL.
<http://blog.niqnutn.com/>
<a href="http://blog.niqnutn.com/">http://blog.niqnutn.com/</a>
Le rendu final:
La même chose est valable pour les adresses mail (avec un encodage de l'adresse mail supplémentaire).
<dontSpam@niqnutn.wolrd>
<a href="mailto:dontSpam@niqnutn.wolrd">dontSpam@niqnutn.wolrd</a>
Le rendu final:
La gestion des images
Pour faire joli, on peut également ajouter des images. La syntaxe est similaire aux liens. On ajoute au début !, puis [Texte à afficher si l'image n'apparait pas], suivi de l'URL de l'image (ex: /path/to/img.jpg) et optionnellement une description (affiché dans l'info-bulle au survol de l'image).
<img src="/path/to/img.jpg" alt="Logo Markdown" title="Markdown" />
Le rendu final:
et si l'image n'existe pas:
La mise en forme
Pour faciliter la lecture on peut utiliser la mise en forme du texte avec l'utilisation du gras, italique, etc.
Pour mettre le texte en italique, on encadre le texte avec *.
*Texte en italique*
<em>Texte en italique</em>
Le rendu final:
Texte en italique
Pour mettre le texte en gras on encadre le texte avec **.
**Texte en gras**
<strong>Texte en gras</strong>
Le rendu final:
Texte en gras
Pour insérer un retour à la ligne au sein d'un paragraphe (<br />), on ajoute deux espaces suivi d'un retour à la ligne.
War is peace.
Freedom is slavery.
Ignorance is strength.
<p>War is peace. <br />
Freedom is slavery. <br />
Ignorance is strength.</p>
Le rendu final:
War is peace.
Freedom is slavery.
Ignorance is strength.
Pour ajouter une ligne horizontale, on utilise ***.
***
<hr />
Le rendu final:
Insérer une citation
Pour les citations il suffit d'ajouter > en début de ligne.
> He who controls the past controls the future. He who controls the present controls the past.
> The best books... are those that tell you what you know already.
> __George Orwell__, _1984_
<blockquote>
<p>He who controls the past controls the future. He who controls the present controls the past. <br />
The best books... are those that tell you what you know already. <br />
<strong>George Orwell</strong>, <em>1984</em> </p>
</blockquote>
Le rendu final:
He who controls the past controls the future. He who controls the present controls the past.
The best books... are those that tell you what you know already.
George Orwell, 1984
Insérer du code
Pour insérer du code (le texte est alors interprété littéralement), on ajoute quatre espaces avant le texte.
apt-get install niqnutn
<pre><code>apt-get install niqnutn</code></pre>Le rendu final:
apt-get install niqnutn
On peut également ajouter du code à l'intérieur d'un paragraphe avec le caractère ` (guillemets obliques) .
Entrer dans le terminal la commande `apt-get install niqnutn` pour installer un paquet.
<p>Entrer dans le terminal la commande <code>apt-get install niqnutn</code> pour installer un paquet.</p>
Le rendu final:
Entrer dans le terminal la commande
apt-get install niqnutnpour installer un paquet.
Et un peu de html
Dans le cas ou la syntaxe Markdown ne couvre pas vos besoins, il est possible d'ajouter directement du code HTML. Il sera interprété automatiquement et il n'est pas nécessaire d'indiquer qu'on change de langage.
<table>
<tr> <th>Distribution</th> <th>Nom</th> <th>Version</th> </tr>
<tr> <td>Debian</td> <td>Jessie</td> <td>8.0</td> </tr>
</table>
<table>
<tr> <th>Distribution</th> <th>Nom</th> <th>Version</th> </tr>
<tr> <td>Debian</td> <td>Jessie</td> <td>8.0</td> </tr>
</table>
Le rendu final:
Distribution Nom Version Debian Jessie 8.0
Caractères d'échappement
Tous les caractères spéciaux sont automatiquement convertis (ex: & devient &). Il faut ajouter \\ pour éviter que certains caractères soient interprétés lors de la conversion.
\\ backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash mark
+ plus sign
- minus sign (hyphen)
. dot
! exclamation mark
Convertir un document Markdown
Une fois le document rédigé, on peut le convertir au format HTML.
markdown /path/to/file/comment-rediger-en-mardown.md
On peut envoyer directement le résultat dans un fichier .html.
markdown /path/to/file/comment-rediger-en-mardown.md > /tmp/comment-rediger-en-mardown.html
Geany dispose d'un terminal intégré. Il n'est donc pas nécessaire de changer de fenêtre.
Aller plus loin avec Markdown
Il est possible d'utiliser des références lorsque l'on utilise de nombreux liens dans un document.
L'utilisation des références permet d'avoir un aperçu final proche de celui d'un navigateur web.
On définit d'une part le texte à afficher: DuckDuckGo est le texte qui sera lisible suivi de 1 qui servira d'identifiant.
D'autre part, on définit les liens: On reprend son identifiant 1, suivi de son URL https://duckduckgo.com/ et optionnellement DuckDuckGo qui sera utilisé comme titre.
Il existe de nombreux moteurs de recherches tels que [DuckDuckGo][1], [Qwant][qwant] ou [ixquick][].
[1]: https://duckduckgo.com/ "Moteur de recherche DuckDuckGo"
[qwant]: https://www.qwant.com/ "Moteur de recherche Qwant"
[ixquick]: https://ixquick.com "Moteur de recherche ixquick"
Il existe de nombreux moteurs de recherches tels que <a href="https://duckduckgo.com/" title="Moteur de recherche DuckDuckGo">DuckDuckGo</a>, <a href="https://www.qwant.com/" title="Moteur de recherche Qwant">Qwant</a> ou <a href="https://ixquick.com" title="Moteur de recherche ixquick">ixquick</a>.
Le rendu final:
Il est aussi possible d'utiliser une image comme lien.Il existe de nombreux moteurs de recherches tels que DuckDuckGo, Qwant ou ixquick.
[](http://blog.niqnutn.com "nIQnutn's blog")
<p><a href="http://blog.niqnutn.com" title="nIQnutn's blog"><img src="data/img/alien.png" alt="alt" title="logo" /></a></p>Le rendu final:
L'imbrication des différents éléments nécessite parfois quelques connaissances et astuces.
Ressources
- Projet Markdown
- Markdown: syntaxe et la traduction française pour les anglophobes.
- Dingus: tester Markdown en ligne
- Debian packages: Geany et geany-plugin-markdown
- Debian packages: Markdown
2016 nIQnutn CC-BY
