Urbanbike

Recherche | mode avancée

Apprenez Markdown en 8 jours | version revisitée

…8 heures ou 8 minutes si motivé…!

dans dans mon bocal | écrire | groummphh | mémoire
par Mark Dukown

Ce billet remplace la première version1 publiée le 1/10/ 2013. L’idée sous-jacente est toujours celle de faire maigrir vos fichiers texte — et eux-seuls…! — idée qui a inspiré (sic…!) le nom de cette méthode2.

Quand j’évoquais ce balisage3 en 2011 à des personnes dont cela simplifierait la vie (…simples utilisateurs, auteurs, journalistes, blogueurs, étudiants, consultants…), j’avais droit à :

— Oh, mais c’est trop compliqué ! suivi, en général, de…

  • les balises sont incompréhensibles,
  • c’est très laid,
  • j’utilise le même traitement de texte depuis des années,
  • (suivi de…) je ne suis pas près d’en changer,
  • le format .txt n’est pas sérieux.

Si ce sont vos arguments, restons en là… Par contre, si vous voulez plus de détails, les notes en bas de billet vous conduisent vers des informations complémentaires…

Bref, peu à peu, ce balisage s’est installé naturellement et ne suscite plus l’ironie, voire des commentaires surréalistes à propos de ses astérisques cosmétiques, des premiers temps…

Reprenons calmement…

Sans me positionner comme un inconditionnel du Markdown (quoi que…), L’idée de ce billet est de revisiter en douceur les bases de ce balisage enfantin. À vous de le mettre en œuvre dans votre quotidien, à votre rythme…
Ou non.

Paris, impasse du côté de l’avenue Montaigne

Bref, ne soyez plus perdus…!

Quels outils…?

Pour mémoire (…il suffit de parcourir ces notes pour le vérifier), je n’évoque ici que des traitements de texte sur Mac, iPad ou iPhone. Bref, les seuls que je connais.

Vous pouvez employer votre traitement de texte habituel, baliser au clavier. Mais c’est (très) vite chhhh…heuuuu… pénible même si cela reste parfois indispensable.

Autant employer l’une des applications ad hoc disponibles sous OSX ou sous iOS. Certaines gratuites ou à coût modique vous offrant l’opportunité d’essayer sans avoir eu la désagréable impression d’avoir dilapidé l’argent du ménage…

Seules les applications les plus évoluées) vous permettront d’exporter votre texte balisé en Markdown dans des formats comme RTF, HTML, PDF, docx, ePub, etc. Aussi, avant d’acquérir l’une d’elles, vérifiez ses options d’exportation

Une petite liste de ceux que j’emploie, dans le désordre, les prix indiqués sont ceux piochés pour information au moment de l’écriture de ce billet…
Recherchez dans ce blog mes diverses contributions sur ces outils.

Sous OSX

Sous iOS…

Sous iOS, les traitements de texte Markdown disposent d’une barre additionnelle qui vous permettra d’appliquer les balises sans avoir eu besoin de les saisir.

J’ai fréquemment évoqué ici mes propres flux de production. Lire urbanbike | À quoi carburent mes écrans | 7

Une approche minimale

Ce qui suit est un mémo par petites étapes (en jours, heures ou minutes…!) des choses à savoir pour tapoter ses textes…

Jour 1 – Italique et Gras
Jour 2 – Paragraphes et retour forcé…
Jour 3 – Titres et niveaux…
Jour 4 – Les listes à puce ou numérotées
Jour 5 – Blockquote ou texte en retrait
Jour 6 – Les liens vers le web…
Jour 7 – Les liens vers les images…
Jour 8 – Code et autres subtilités…


Jour 1

Commençons par les commandes clés, celles dont vous avez impérativement besoin au minimum dans un traitement de texte…

Italique et Gras

Ce sont souvent les mêmes équivalents clavier en général que dans n’importe quel traitement de texte sous OSX…!

  • Sous OSX, si vous effectuez un Commande-I sur une sélection, hop (!!), votre sélection passe en italique… Et cela se visualise ainsi *italique*
  • Idem, si vous faites Commande-B sur une sélection, le gras s’applique… Cela s’écrit ainsi **gras**
  • Si vous faites le combo Commande-B suivi de Commande-I sur une sélection, vous obtenez du gras italique… qui se distingue par ses trois astérisques ***gras italique***

Attention, tous les traitements de texte ne supporte pas ce combo (il vous faudra alors ajouter des astérisques au clavier) et, pour ma part, je n’utilise plus le style caractère gras + italique depuis des années…

Simple non…?!

Sous iOS, il suffit de sélectionner le texte et utiliser l’une des touches ad hoc de changement de graisse sur la barre additionnelle qui surmonte le clavier tactile et les trois cases prédictives pour entourer la sélection des balises idoines.

C’est tout…

Notez que vous pouvez employer des _ (des underscores) en lieu et place des *. Ainsi ce ___texte est en gras italique___ comme ***cet autre texte en gras italique***. Mais cela reste moins simple à lire …à mes yeux.

Un exemple dans iA Writer sur Mac

Rappel utile : dans les applications citées en amont, il existe une fenêtre de visualisation du rendu de votre balisage, une preview qui vous permettra immédiatement de voir le résultat de votre saisie. Pensez à vous y référer régulièrement au départ pour vérifier le bon emploi de vos balises. Sur iA Writer ⚑ ou MultiMarkdown Composer 2 ⚑ sur OSX, la fenêtre peut être séparée en deux, permettant ainsi de suivre instantanément le tout, écriture et rendu. D’autres comme Ulysses ⚑ proposent la coloration syntaxique qui permet d’attribuer une couleur à chaque type de balise comme les outils de développement.


Jour 2

Comment gérer les paragraphes en Markdown.

Paragraphes et retour forcé…

  • Un paragraphe, c’est une série de phrases à la suite…
  • Par contre, si vous séparez vos textes par une (ou plusieurs) lignes creuses (vides), vous créez des paragraphes.
  • Question que tout le monde se pose : comment créer un retour forcé dans un paragraphe…? Très simplement en ajoutant deux espaces vides en fin de ligne suivi d’un simple retour ligne (↩).

En résumé :

Ceci est un premier paragraphe.

Une ligne vide avant, second paragraphe.

Deux espaces vides avant le retour ligne…
Bingo ! Ceci est un retour forcé…

Ça s’écrit comme cela…

`Ceci est un **premier paragraphe**.

Une ligne vide avant, second paragraphe.

Deux espaces vides **avant** le retour ligne…   
**Bingo !** Ceci est un retour forcé… 


Jour 3

Un document est généralement composé des titres de niveaux différents entrecoupés de contenu, que ce soit juste le nom des chapitres ou le plan même d’un rapport.

Titres et niveaux…

En Markdown, il faut impérativement faire précéder le titre d’un (…ou plusieurs) # suivi d’une espace. Et détacher ce titre du texte courant par une ligne vide avant et après…

Du coup, cela se note ainsi :

# Je suis un niveau 1
## Je suis un niveau 2

Et ainsi de suite…

### niveau 3
#### niveau 4
##### niveau 5
###### niveau 6

Deux options à connaître…

Les inventeurs du Markdown ont imaginé des options mais sont-elles à suivre aveuglément…? Éléments de réponse…!

  • Certains puristes ajoutent le même nombre de # en fin de ligne. Si vous changez fréquemment votre titre de niveau, il vous faudra intervenir deux fois dans le même titre pour modifier son niveau.

##### niveau 5 #####
###### niveau 6 ######

Bref, une option esthétique… que je n’utilise pas

  • Pour mémoire, vous avez à votre disposition une mise en forme qui prend sa source dans l’utilisation des machines à écrire mécaniques d’avant l’informatique pour différencier visuellement les deux premiers niveaux avec un soulignement…

Niveau 1
========

Niveau 2 => mais seulement une ligne… piège…!
----------------------------

Vous n’êtes pas obligé de tout souligner. Et pas plus l’utiliser.

Certains traitements de texte comme Editorial ⚑ sous iOS ou FoldingText ⚑ sous OSX permettent de ne voir qu’un niveau en masquant tous les autres, ce qui est très confortable sur un seul et long fichier structuré.
Créer des niveaux ne permet pas de fabriquer pour autant des sommaires automatiques en Markdown. C’est pourquoi il est intéressant de regarder du côté de MultiMarkdown (qui emploie les mêmes balises mais en ajoute de nouvelles). Dernière balise ajoutée, {{TOC}} qui permet de rassembler tous les niveaux4 dans l’ordre comme une table dès matières.

C’est tout.


Jour 4

Organiser des listes, deux options d’une simplicité confondante…

Les listes à puce ou numérotées

Il suffit de faire précéder son paragraphe…

  • d’une *pour une liste à puce. Vous pouvez également employer un signe + ou un signe -
  • mais impérativement suivi d’une espace…
  • un chiffre comme 1. pour les listes numérotées. Vous pouvez mettre toujours un 1 par défaut, ce sera ensuite incrémenté par votre outil Markdown.
    • Notez que si vous ajoutez une tabulation (…ou 4 espaces blancs)
    • et bien sûr, avant le symbole * ou 1.
      • …Vous pouvez décaler votre liste

Un exemple de liste à puces…?

  • une puce
  • une autre puce
    • Là, c’est une invasion…!

Et cela s’écrit :

une puce
une autre puce
    
c’est une invasion…

Et les listes numérotées…?

  1. Oui, ça fonctionne aussi
  2. avec les listes numérotées…
    1. Avec retrait…
  3. Et hop, ça redémarre…
  4. au niveau de la numérotation…

Et cela s’écrit :

1. Ouiça fonctionne aussi
2. avec les listes numérotées…
    1. Avec retrait…
5. Et hop
ça redémarre…
7. au niveau de la numérotation… 

À suivre.


Jour 5

Ajouter une citation, rythmer un flux de texte…

Blockquote ou texte en retrait

J’aime bien mettre en exergue un texte ou marquer une citation…

  • Facile : démarrer la phrase par la caractère > suivi d’une espace
  • Et si vous ajoutez une tabulation avant le >, hop, retrait… (autre option, multiplier les > comme ceci >>)

Exemple…

Une citation…
    
Second niveau de citation… etc

Ou…

Une citation…
>> Second niveau de citation… etc

Employer les caractères utilisés dans les balises dans votre texte

Comment employer >, # ou * dans un paragraphe sans que cela interfère avec le balisage Markdown ?

En faisant précéder ce caractère d’un backslash, c’est à dire cet autre caractère \

Ainsi un * astérisque, deux ** astérisques, un > ou un \# qui ne seront pas interprétés… Le backslash \ inhibe l’interprétation du Markdown et s’écrit \* — \*\* — \> — \# — \\

Voilà.


Jour 6

Bon, je ne vais évoquer que les liens Markdown versus ceux en HTML.

Les liens vers le web…

Ben oui…?! Comment faire un lien, ajouter une URL vers une page sur le net dans un texte courant en Markdown ?

Théoriquement, en HTML, on devrait écrire ceci avec <a> et </a> au début et à la fin :

<a href="http://urbanbike.com">Urbanbike</a>

En Markdown, c’est simplement :

[Urbanbike](http://urbanbike.com)

Mais si vous ne souhaitez voir l’url (…qui peut être fort longue) dans le texte, Markdown vous offre une possibilité qui j’apprécie énormément (et utilise peu…!), celle de ranger en fin de texte (ou sous le paragraphe courant) ces URLS…

[urbanbike][1] et [Photager][2]

[1]: http://urbanbike.com
[2]: http://photager.com

Pour éviter de se tromper de numéros, vous pouvez renseigner chaque url avec une référence plus explicite…

[urbanbike][uba] comme [Photager][pho]

[pho]: http://photager.com
[uba]: http://urbanbike.com

Notez que l’ordre de ces liens en fin de document n’a pas d’importance…

Voilà, voilà…


Jour 7

Comment ajouter dans votre texte un lien vers une image sur le net ?

Les liens vers les images…

Théoriquement, on devrait écrire ceci en HTML :

<img src="http://site.com/dossier/image.jpg"
alt="explication" title="information" />

En Markdown, c’est juste cela :

![texte alternatif](http://site.com/dossier/image.jpg)

Ou ça (…si votre CSS, voir en fin de billet)…

![texte alternatif](lien-vers-image "info-en-plus")

Ce qui change par rapport à un simple lien (cf. étape précédente), c’est l’! en tête qui signale que l’on a affaire à une image…

Marathon de Paris 2016

Par exemple, cette image est balisée…

![Marathon de Paris 2016](http://www.urbanbike.com/images/uploads_2016/20160406-mk-3791.jpg "info-en-plus")

"info-en-plus" permet d’ajouter une info qui, lors du survol du pointeur sur l’image sur urbanbike par exemple, s’affichera…

Oui mais comment spécifier la taille, l’habillage ? Tssss… Ça, c’est le rôle des CSS (…et d’un autre billet)

L’intérêt…?
Votre fichier reste en texte pur sans s’encombrer des images (et restera ultra svelte !)… Mais affichera en mode prévisualisation (et lors de l’export…) les illustrations dont le chemin est connu…

À suivre…


Jour 8

Bon, vous avez vu les balises essentielles pour écrire. Et découvert que c’était loin d’être compliqué ou usine à gaz, loin d’être laid et de brouiller votre écriture vu que les balises Markdown sont généralement affichées en gris… Bref, c’est simple, vous êtes concentré sur votre texte et la qualité de vos contenus s’en ressentent. Pourquoi !? Parce que vous n’êtes plus en train de passer, en permanence, de la rédaction à la mise en forme (et réciproquement).

Si vous effectuez une rapide comparaison du poids de vos anciens fichiers avec format propriétaire avec ceux au format .txt balisés en Markdown, certains sont passés de 300ko à 5Ko.

Plus rapides à partager, à sauvegarder (…tant en local que sur le cloud), vous les enregistrez au format .txt, .md, .markdown… C’est du texte qui circule sans souci entre OSX et iOS ou via DropBox, iCloud.

Code et autres subtilités…

Pour finir, quelques petites options en plus dont certaines empruntées au MultiMarkdown.

Filet horizontal

Tiens, basique, comme ajouter un filet horizontal, le fameux <HR> bien connu en HTM…? Comme ce qui suit…


Très compliqué, trois tirets à la suite bien séparés des paragraphes qui précèdent ou qui suivent…!

---

Faire ressortir le Code

Comment faire ressortir du code ? Deux manières fort simples.

  • Dans une phrase, ce qui doit être affiche comme du code est placé entre deux signes `` (les fameux backticks)
  • Détaché entre deux paragraphes, l’habituel <pre> HTML. En Markdown, il suffit de démarrer la ligne par une tabulation (ou 4 espaces vides) et ce qui suit est interprété comme du code. C’est basique et ce billet est rempli d’exemples…
Notes en bas de page

Au début de ce billet, il est écrit balisage Markdown. Effectivement, on peut aller encore plus loin grâce au MultiMarkdown. Et donc s’en servir pour des notes en base de page.

La notation la plus sûre est d’utiliser un appel de [^note]puis de placer une ancre avec le contenu de la note en fin de texte.

[^note]: mon texte de note

Comme nous ne sommes plus dans Markdown mais dans MultiMarkdown, sachez que cette déclinaison évolue régulièrement et, récemment, une nouvelle manière de spécifier une note inline footnote — note imbriquée — commence à se diffuser5.

Ici, la [^note s'écrit sans appel de note]

Tableaux

C’est à un balisage rustique auquel Markdown nous convie…

En résumé, se souvenir que c’est la seconde ligne du tableau Markdown qui va gérer les alignements des cellules…
Exemple du code :

Année | CA | TVA | TTC
| :---: | ---: | :---: | ---: |
2010 | 3 200 | 19,6 % | 3 827,20
2011 | 6 500 | 19,6 % | 7 774,00
2012 | 14 500 | 20,6 % | 17 487,00

En n’oubliant pas les pipes | pour marquer et séparer les cellules ainsi que les infos d’alignement très sioux (notez la position du signe :)…
Centré :---:
Fer à droite ---:
Fer à gauche :---

Cela donne :

Année CA TVA TTC
2010 3 200 19,6 % 3 827,20
2011 6 500 19,6 % 7 774,00
2012 14 500 20,6 % 17 487,00

Et, bien sûr, avoir une stratégie adéquate pour les alignements et, bien entendu la stylisation des cellules.

| Images | Tableaux | *Rappel*
| :--- | :---: | :---: | ---: |
**Word like** | Oui | Oui | *habillage possible*
**Markdown** | Oui | Oui | *rendu selon la CSS active*

Images Tableaux Rappel
Word like Oui Oui habillage possible
Markdown Oui Oui rendu selon la CSS active

Le rendu des tableaux va dépendre de la CSS employée (ici, celle de Bootstrap) ce qui me permet d’arriver subtilement sur la dernière note (ruse !).

Exporter votre fichier

Encore une fois, Markdown ne met pas en forme votre contenu. Il permet d’insérer les balises pour indiquer que telle partie du texte est en gras, que tel titre est un niveau 3, que tel paragraphe est une citation, telle précision s’affichera comme une note en bas de page.

Formats d’export

Une fois arrivé au bout de votre saisie (votre fichier source serais-je tenté de dire) dans des conditions de confort incomparables, reste à exporter ceci dans le format dont vous avez besoin pour un usage donné…

  • en Markdown (si, si !) vers WordPress ou ExpressionEngine, nombre de CMS pour la Web supportent Markdown
  • en HTML sans aucun problème…
  • en RTF ou en .docx pour communiquer avec des traitements de texte bureautiques
  • en PDF avec la CSS proposée par les développeurs du traitement de texte que vous employez
  • au format ePUB si vous avec rédigé un fascicule, aide-mémoire, roman, outil de formation…
  • …et même vers InDesign
CSS et mise en forme

Chaque traitement de texte Markdown propose des options de mise en forme pour un export en PDF par exemple.

  • Byword ⚑ vous propose une CSS pour l’export,
  • iA Writer ⚑ trois,
  • Ulysses ⚑ des dizaines…
  • Et Marked2 ⚑ — qui n’est pas un traitement de texte, rappel utile — met tout le monde d’accord, prenant le fichier .txt de votre choix et l’exportant avec la CSS de votre choix.

Notez que je ne parle pas de formats mais bien de mise en forme. La CSS est simplement un fichier de mise en forme6 du contenu. C’est cette segmentation entre texte structuré et joli rendu (sic…!) qui rend Markdown rapide, léger et idéal pour rédiger.

Allez, vous avez le droit de souffler…! Et moi de me relire (ce texte sera certainement revu dans les semaines qui viennent…!)

Bords de Seine

C’est tout pour ce billet…

Ah si, dernier point…! Un texte balisé en Markdown n’est pas prisonnier du traitement de texte qui a servi à le saisir (je ne vois pas à quel outil je fais implicitement référence…!), mes propres textes se baladent d’application en application selon mes besoins…


  1. À la relecture de la version potache de 2013, pas mal de scories, répétitions, lourdeurs que j’ai tranquillement benné ! 

  2. Méthode Dukown,CQFD. Tout ce qui est relaté ici est disponible depuis 2004 sur le net… Retrouvez les instructions en anglais de son inventeur, John Gruber, celles proposées par les concepteurs de Byword dans leur Byword MultiMarkdown Guide en passant par des tas de [fiches][38] comme celles de Michel Fortin ou encore un résumé sur Wikipedia

  3. Cf. urbanbike | Markdown et écriture | 1 et les textes suivants… Ou encore ces billets : urbanbike | Tu es vieux et Markdown te passe au-dessus des oreilles ?! | urbanbike | Markdown, une révolution silencieuse ? | urbanbike | Perdu avec Markdown…? À quoi cela sert…? Quelques explications… 

  4. Cf. urbanbike | La balise TOC s’invite dans les outils MultiMarkdown 

  5. Un exemple dans 1Writer ⚑ sous iOS illustré ici : urbanbike | iA Writer 3.0 et note de bas de page 

  6. Ce que vous lisez actuellement sur urbanbike dépend d’une CSS, le texte de départ est sans aucun artifice de mise en forme et juste balisé en Markdown. Sauf pour les tableaux car ExpressionEngine ne supporte pas MultiMarkdown et j’ai du convertir pour les besoins de ce billet les tableaux en HTML. 

le 06/04/2016 à 10:20 | .(JavaScript must be enabled to view this email address) à Mark Dukown | Partager…?