nIQnutn

Le numérique libre en contre-addiction

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).

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.


#root
apt-get install geany geany-plugin-markdown markdown

On démarre Geany depuis le menu: Développement > Geany
ou directement depuis le terminal:


$user
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.

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

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
* ...

Pour les listes non ordonnées, on utilise un nombre suivi d'un point (ex: 1.).

1. Premier
2. Deuxième
3. Troisième
Les nombres utilisés n'ont pas d'importances et ne sont pas interprétés.

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")

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).

Encore plus simple, il est possible de créer des liens automatiquement à partir d'URL.

<http://blog.niqnutn.com/>

La même chose est valable pour les adresses mail (avec un encodage de l'adresse mail supplémentaire).

<dontSpam@niqnutn.wolrd>

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).

![Logo Markdown](/path/to/img.jpg "Markdown")
Markdown ne permet pas de définir la taille des images. Dans ce cas, il est possible d'utiliser les tags HTML .

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*

Pour mettre le texte en gras on encadre le texte avec **.

**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.

Pour ajouter une ligne horizontale, on utilise ***.

***

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_
Pour plus de lisibilité on ajoute > à chaque nouvelle ligne.

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
Tous les caractères seront échappés.

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.

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>

Caractères d'échappement

Tous les caractères spéciaux sont automatiquement convertis (ex: & devient &amp;). 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.


$user
markdown /path/to/file/comment-rediger-en-mardown.md

On peut envoyer directement le résultat dans un fichier .html.


$user
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 est aussi possible d'utiliser une image comme lien.
[![alt](data/img/alien.png "logo")](http://blog.niqnutn.com "nIQnutn's blog")
Il est conseillé de lire la documentation concernant la syntaxe si on souhaite utiliser Markdown plus profondément.
L'imbrication des différents éléments nécessite parfois quelques connaissances et astuces.

Ressources

6 commentaires

Cascador |

Super tuto bravo !

Référencé sur le Journal du Pirate.

Tcho !

nIQnutn |

@Cascador :
Merci.
J'essaie de faire des choses utiles en me basant sur mon expérience et d'apporter un petit plus sur ce qui a déjà été dit et fait.

Cascador |

J'ai l'impression que tu t'inscris tout comme moi dans la qualité, j'ai écrit un article là-dessus : http://www.laurent-napias.com/post/2015/05/06/le-temps-de-la-qualite

Il est clair que faire des articles complets, didactiques, intéressants, ça fait un tabac. Tu as d'ailleurs creuver le plafond avec ton article KeePassX, 6 votes pour ton article chez nous.

En tout cas bravo, c'est franchement super intéressant les articles que tu fais.

Tcho !

nIQnutn |

@Cascador :

Il y a suffisamment de choses écrites, sur de nombreux sujets sur le web. Refaire la même chose n'a que peu d'intérêt, dans ce cas, je publie sur Actualités.

J'essaie d'avoir une certaine "qualité" et être relativement complet dans tout ce qui est publié. J'essaie de garder ce cap, mais j'accepte toutes les critiques constructives parce tout peut être amélioré.

En tout cas, ça fait toujours plaisir d'être lu et encore plus si ça plaît.

J&#039;informatique |

Utilises-tu un plugin dans PluXml pour écrire en Markdown?

Est-ce que celui qui existe est pratique car je ne l'ai pas encore testé.

Merci.

nIQnutn |

@J&#039;informatique :
Non je n'ai pas utilisé de plugin spécifique à PluXml. Pour le moment je reste avec plxtoolbar.

J'utilise le Markdown pour la rédaction, hors ligne avec Geany. Je convertis puis je finis la mise en page avec dans l'éditeur de PluXml (principalement l'ajout de médias).

Fil RSS des commentaires de cet article

Écrire un commentaire