Le Markdown

Vous avez surement déjà croisé ce mot dans des articles ou sur des forums.

Il fait partie de la panoplie des outils un peu rugueux qui me plaisent tant.

Markdown est un langage ultra simple qui permet d'écrire du HTML de façon raccourcie, de mettre en forme du texte à l'aide de quelques signes typographiques. Il permet de mettre en gras, en italique, de hiérarchiser les titres (h1…h5), de faire des listes et des listes numérotées, de formater des liens, d'ajouter des images et en dernier lieu de mettre en forme du code.

Il permet ce que permettent des outils basiques comme TextEdit et le .rtf (Rich Text Format), il suffit d'un simple éditeur de texte ou de code pour en produire. Il est couramment utilisé pour les fichiers de documentation d’un projet ou d’un jeu de données -souvent nommé readme.md (sur github p.ex.). Il est stocké au format texte classique et est plus léger que sa version interprétée puisqu’il ne contient pas les balises html.

La philosophie du système veut que le texte écrit soit lisible sans interpréteur particulier en mode texte. Il est léger et épuré de l’essentiel de la verbosité d’un language balisé.

il suffit donc d'écrire :

**gras** pour avoir gras,

_italique_ pour italique,

# Titre 1 en début de ligne pour obtenir du <h1>Titre 1</h1>,

## Titre 2 en début de ligne pour obtenir du <h2>Titre 2</h2> etc...

bref facile!

Il y a deux "versions" du markdown, la syntaxe standard et la syntaxeétendue.

La syntaxe markdown étendue ajoute :

tables (les données tabulaires)
code blocks (les blocs de code)
syntax highlighting pas pris en charge par les lib testées
URL auto-linking pas pris en charge par les lib testées
footnotes (les notes de pied de page)

J'ai uniquement cherché des librairies js ou php qui géraient, tout ou partie de la syntaxe étendue.

Je vous renvoie, pour un peu plus d'infos, vers un article d'openclassroom et une traduction du manuel et vous pouvez tester ici.

exemple

Écrire du markdown

à la main

Comme le langage est très simple à mémoriser (au moins pour le texte standard), avec un simple éditeur de texte (TextEdit par ex.) on peut écrire en markdown. Le pb c'est de prévisualiser... Avantage, sur MacOs au moins (je crois aussi sous w10) on bénéficie du correcteur orthographique. Je suis fâché avec les accents, c'est assez agréable quand l'éditeur souligne les choses douteuses.

avec Atom + le package markdown-writer (MacOS, Windows)

ça a été mon premier outil d'écriture md. La barre d'outils qui s'ajoute lorsqu'on travaille un fichier .md permet d'accéder à l'essentiel (h1 -> h3, gras, italique, lien, image).

J'aime bcp l'outil d'image qui permet d'importer des images et de récupérer ses dimensions.

Le plugins est configuré pour être, les anglo-saxons disentGithub flavored, en français on dirait à la sauce Github, c'est à dire que : comme github ne gère pas la taille des images, le plugins n'en tient pas compte lors de la transcription.

En fouillant un peu le net, j'ai trouvé comment modifier cela (cf. en fin d'article le point technique sur le sujet ).

Il n'y a pas de correcteur orthographique…

atom_markdown-writer_2

C'est austère mais gratuit.

avec Ia Writer (MacOS, iPadOS)

ia writer est un éditeur de texte markdown, hyper sobre, hyper minimaliste, qui se concentre sur l'écriture.

ia_writer

L'application coûte 32,90€ sur l'App Store, il synchronise les fichiers sur iCloud (oui mais pas moi…)

L'éditeur existe aussi sur iOS, et là, iCloud prend tout son sens pour synchroniser son travail d'écriture d'une plateforme à l'autre (j'ai découvert ia writer grace à J-C Courte d'urbanbike qui raconte, entre autres choses, la dématérialisation de ses prises de notes et des outils qu'il a bcp testé et qu'il utilise).

Quand on ne connait que Word™ ou Open Office™, c'est déroutant: l'interface est vide. Passé la désorientation du démarrage, la prise est de fait rapide, c'est très bien pensé, très agréable d'écrire avec.

La barre d'outils placée en bas est spartiate mais contient l'essentiel (niveau de titre, gras, italique, lien, liste,,,). Elle disparaît lorsque la souris n'est pas au dessus. On peut régler sa présence permanente dans les prefs.

avec Caret (MacOS, Windows)

Caret est un éditeur de markdown comme ia writer - sobre et minimaliste.

caret_1

Le logiciel vaut 29$ (TTC), mais la version d'évaluation est sans fin. Comme dans Sublime Text, de temps en temps, un écran propose de l'acheter, il faut appuyer sur la touche esc pour revenir au travail, après quelques secondes.

Le logiciel est un peu plus complet qu'ia writer, mais il faut aller chercher dans le menu Format pour styler, ou utiliser les qlq raccourcis clavier (Command + b pour le gras, Command + i pour l'italique, Command + k pour les liens), ou encore directement écrire le style markdown. J'avoue que c'est moins pratique que la barre d'outils d'ia writer mais les 3 raccourcis sont mémorisables

On peut ajouter des images en glissant un fichier image dans le texte, ça prévisualise et écrit le code de base, qu'on peut compléter pour avoir le dimensionnement. J'avoue aussi que ça me manque de ne pas l'avoir comme dans markdown-writer sur Atom.

C'est une interface minimaliste qui se concentre sur l'écriture comme ia writer (fond noir ou blanc, texte en cours au centre de l'écran).

L'éditeur affiche le texte stylé en plus des signes typo qui servent à le créer (ia writer le fait aussi mais ça paraît plus discret, sans doute à cause de la typo par défaut ). C'est très pratique et très bien fait visuellement.

C'est très agréable d'écrire avec. Il y a le correcteur orthographique, qui souligne mes fâcheries d'accents et mes fautes de frappe. C'est vraiment élégant graphiquement

Les options d'édition d'ia writer sont peut être un peu meilleures, quoi que… Les deux éditeurs se valent.

Pour les départager, je dirais que ia writer est orienté écriture, Caret plus orienté écriture de notices pour développeurs.

Et pour tout dire, j'ai commencé à écrire cet article avec Atom, puis ia writer et j'écris ces lignes avec depuis qlq heures, avec bcp de plaisir sur Caret.

Travailler en markdown

Dans Indesign

Markdown.jsx par Melchior Brislinger

~~pas encore testé.~~

https://github.com/melchiorb/indesign-scripts

MarkdownID.jsx par Jongware

~~pas encore testé.~~

http://www.jongware.com/binaries/markdownid.zip

Dans une page web

En php

rapidement, php est un langage serveur qui permet de générer des pages html.

MarkDownExtra - lib php

J'ai d'abord utilisé la lib. de Michel Fortin , MarkdownExtra disponible sur Github

La mise en œuvre est simple (il a quand même fallu que je cherche un peu, l'exemple d'intégration donné n'est pas très clair pour un débutant en php):

L'avantage de php est que la récupération d'un fichier sur le serveur se fait en une seule ligne avec file_get_contents()

<?php
  // importe la lib markdown
  require_once 'Michelf/MarkdownExtra.inc.php';
  use Michelf\MarkdownExtra;
  // récupère le nom du fichier passé dans l'url
  $fichier = $_GET['f'];
  // ouvre le fichier md
  $my_text = file_get_contents($fichier, true);
  // transforme le md en html
  $my_html = MarkdownExtra::defaultTransform($my_text);
  // écrit le contenu formaté
  echo $my_html;
?>

ParsedownExtra - lib php (7.3 max)

J'ai ensuite utilisé une autre lib Parsedown, qui est plus rapide, plus récente et du même éditeur que Caret (l'éditeur de texte minimaliste dont je parle plus haut). Elle est aussi utilisée sur nombre de CMS dont Kirby (un CMS basé sur une architecture de dossiers/fichiers, j'y reviendrai peut-être).

La mise en place est simple: deux fichiers php à placer sur le serveur (parseDown.php + parseDownExtra.php) et ce bout de code :

<?php
  // importe la lib markdown ParseDown et ParseDownExtra
  require_once 'libs/Parsedown.php';
  require_once 'libs/ParsedownExtra.php';
  // fichier exemple
  $fichier = "_exemple.md";
  // ouvre le fichier md
  $contenu = file_get_contents($fichier, true);
  // instantie un objet ParseDownExtra
  $parserMD = new ParsedownExtra();
  // écrit le contenu transformé en html
  echo $parserMD->text($contenu)
?>

En js

Il y a des libs qui font le travail, mais je dois bien avouer que charger un fichier externe en js, c'est un peu verbeux et que ça découragerait un débutant.

J'ai néanmoins testé Marked avec le code suivant.

NB: ~~les dimensions d'images dans le .md ne passent pas!~~

MàJ 20/03/20: oui mais c'est pas grave, le css s'en charge.

  <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
  <script>
    const getMD = function(url, callback, errorCallback) {
      const xhr = new XMLHttpRequest();
      xhr.open('GET', url);
      xhr.onload = function () {
        if (this.status >= 200 && this.status < 400) {
          callback(this.response);
        } else {
          errorCallback();
        }
      };
      xhr.send();
    };
    getMD(
      "DN2__Atom_customiser_md_image.md",
      (e) => { document.body.innerHTML = marked(e)},
      (e) => {console.log("error:",e)}
    );
  </script>

d'autres lib js:

markdown-it (semble plus complète que la version php (cf. l'image au dessus))
showdown (prend en charge les dimensions d'images dans une syntaxe différente)

![Alt text](url/to/image =250x250 "Optional title")

Améliorer la gestion des images

Donner des dimensions aux images en MD - avec js

MàJ 20/03/20: Attention c'est une version compliquée, le chapitre suivant, c'est une version simple. Mais la solution est une conjonction des deux

Les parser php ou js, ont une conversion un peu simpliste du tag images.

Par défaut, markdown autorise l'ajout d'attributs title, alt et src. Mais quid de la dimension des images?

Ça n'a l'air de rien, mais en préparant ces pages, je rajoute des illustrations qui sont des captures d'écran faites sur un macbook avec écran retina™. Les images sont très grandes, trop grandes et c'est gênant, il faudrait les redimensionner (j'ai la flemme de passer par un logiciel de traitement d'image). Le plus "simple", c'est d'imposer une dimension à l'image, au moins une largeur. Oui je reste avant tout un graphiste, je veux gérer à minima ma mise en page, en contenant la taille des images.

Pour régler ces problèmes de taille, en fouinant j'ai découvert que le langage markdown autorisait l'ajout de dimensions (cf. la note juste en dessous à propos de markdown-writer)

une image en MD s'écrit:

![alt](src){width=largeurpx height=hauteurpx}

showdown (js) utilise une autre syntaxe

![alt](src =largeurxhauteur "title")

Oui mais voilà, ma bonne dame, les parsers ne tiennent pas compte des attributs width et height, et les laissent trainer dans la page (c'est moche) mais surtout ne redimensionnent pas les images comme demandé… (c'est double moche).

J'ai eu beau tester, chercher, rien, que dalle, nada, peau de balle. J'ai rien trouvé.

Donc j'ai écrit un bout de js qui fait le job, à savoir rajouter les attributs à l'image en fonction de ce que le script de traitement laisse trainer.

Je vous le donne, il suffit de copier-coller dans votre page php.

window.addEventListener("DOMContentLoaded", (event) => {
  // ajoute les attributs d'image non pris en charge par les parsers markdown
  const listeImg = document.querySelectorAll("p>img");
  for (const i of listeImg) {
    const rebus = i.nextSibling.textContent.replace(/^ /,"").replace(/ /g, ",").replace(/{|}/g, "").replace(/\n/g,"");
    // enlève la scorie
    i.nextSibling.textContent = "";
    // explose la chaine sur le ","
    const attr = rebus.split(",");
    // génère les attributs de l'image
    for (it of attr) { // itère sur la table générée
      if (/:/.test(it)) { //si le séparateur key : value
        // récupère l'attribut
        const att = document.createAttribute(it.split(":")[0]);
        // récupère la valeur et le donne à "att"
      [,att.value] = it.split(":");
      // ajoute l'attribut à la balise <img>
        i.setAttributeNode(att);
      } else { //si le séparateur key = value
        const att = document.createAttribute(it.split("=")[0]);
        [,att.value] = it.split("=");
        i.setAttributeNode(att);
      }
    }
  }
});

Donner des dimensions aux images MD - avec css

Oui mais voilà, quand on ne regarde pas de façon globale un projet, on cherche une solution qui semble, vue du bout du nez, la bonne.

En fait, il y a bien plus simple : gérer via css.

Et ma fois, après quelques heures de r&d, c'est désarmant de facilité.

img {
  max-width: 600px; /* c'est la largeur de mon bloc texte*/
  height: auto; /* permet de conserver le ratio de l'image */
}

Et puis c'est tout!

MàJ 28/03/20 : En fait, pas tout à fait. J'ai conservé les deux solutions. Parce que parfois, l'image n'atteint pas les 600px, mais n'a pas d'interêt à être aussi grande (c'est encore les captures d'écrans qui posent problème, une capture de menu en x2 c'est inutile. ex. dans le chapitre du dessous)

Customiser markdow-writer dans Atom

Ajouter une image c'est bien mais avec la dimension c'est mieux. Les captures d'écrans retina™ sont trop grands. Il faut les réduire (sans passer par un éditeur d'images).

Dans Atom, on peut utiliser le plugin Markdown-writer et sa barre-outil qui fonctionne comme un éditeur de texte standard. Malheureusement pour rester compliant avec Github, il ne tient pas compte des dimensions d'image qui sont pourtant présents avec les outils d'insertion.

On peut remédier à ce problème en modifiant le tag Image écrit, dans le fichier config.cson d'Atom (Atom > Config…) du plugin. On peut réécrire la balise img avec des attributs de dimension.

Menu Atom {width=206px height=384px}

pour markDownExtra ou ParseDown(php)

"markdown-writer":
    relativeImagePath: true
    imageTag: "![{alt}]({src}){width={width}px height={height}px}"

ou pour showdown(js)

"markdown-writer":
    relativeImagePath: true
    imageTag: "![{alt}]({src} ={width}x{height} \"{title}\")"

~~Malheureusement ça ne prend pas les maths, on ne peut pas diviser par deux le résultat par exemple, il faut le faire à la main :(~~

Le code markdow ressemble à ça:

![AlternatifImage](urlImage){width=largeurImagepx height=hauteurImagepx}

ou à ça:

![AlternatifImage](urlImage =largeurImagexhauteurImage "titre")

~~et le code html produit après interprétation:~~

<img src="urlImage" alt="titreImage" width="largeurImagepx" height="hauteurImagepx">

Cela fonctionne qu'avec la lib markdown de Michel Fortin, sinon ça produit plutôt ça:

<img src="urlImage" alt="titreImage">{width=largeurpx height=hauteurpx}

cf. plus haut le script js pour la correction.