nIQnutn : Rédiger en Markdown
mardi 12 mai 2015 à 09:14Markdown 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, .mdml ou .markdown.
Si le formatage n'est pas pris en compte, pensez à vérifier que votre texte est bien structuré.
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
Titre de niveau 1
Titre de niveau 2
Titre de niveau 3
Titre de niveau 4
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
* ...
- HTML
- CSS
- PHP
- ...
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
- Premier
- Deuxième
- Troisième
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")
nIQnutn
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).
Retour vers le Haut de page ou voir les Actualités.
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.
Le rendu final:
La même chose est valable pour les adresses mail (avec un encodage de l'adresse mail supplémentaire).
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).
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*
Texte en italique
Le rendu final:
Texte en italique
Pour mettre le texte en gras on encadre le texte avec **.
**Texte en gras**
Texte en gras
Le rendu final:
Texte en gras
Pour insérer un retour à la ligne au sein d'un paragraphe (
), on ajoute deux espaces suivi d'un retour à la ligne.
War is peace.
Freedom is slavery.
Ignorance is strength.
War is peace.
Freedom is slavery.
Ignorance is strength.
Le rendu final:
War is peace.
Freedom is slavery.
Ignorance is strength.
Pour ajouter une ligne horizontale, on utilise ***.
***
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_
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
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
apt-get install niqnutn
Le rendu final:
apt-get install niqnutn
Note: tous les caractères seront échappés.
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.
Distribution Nom Version
Debian Jessie 8.0
Distribution Nom Version
Debian Jessie 8.0
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 DuckDuckGo, Qwant ou ixquick.
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")
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
© 2015 nIQnutn - Tous droits réservés.
Original post of nIQnutn.Votez pour ce billet sur Planet Libre.
