Faciliter la saisie avec le langage Markdown

Dans cette vidéo, on va parler du langage Markdown. On va voir ce que c'est et voir comment il peut être utilisé pour nous permettre de créer et de réaliser facilement du contenu pour les pages Internet de notre site.

Regarder la vidéo sur YouTube

Cet article est la 8^e partie d'une série qui explique comment réaliser un site Internet de A à Z. Vous n'avez pas besoin d'avoir lu ou vu les parties précédentes pour comprendre cette partie. Les autres épisodes sont disponibles ici.

Si vous ne pouvez pas regarder la vidéo, un compte rendu est proposé plus bas.

Résumé de la vidéo

Dans les précédentes vidéos, nous avons réalisé la page d'accueil de notre site en écrivant manuellement le code HTML de la page. Cette page contient principalement la liste des derniers articles disponibles, avec des liens pour amener l'internaute vers les pages contenant les articles.

Pour le moment, ces pages d'articles n'ont pas encore été réalisées, mais nous allons le faire maintenant.

Pour réaliser ces pages d'articles, on pourrait très bien l'écrire de façon traditionnelle, c'est-à-dire en écrivant le contenu de la page en HTML, comme nous l'avons fait pour la page d'accueil.

Le résultat ressemblerait à ça, si je reprenais une partie de l'article que j'ai écrit sur la création d'un backend en Node.js :

<h2>Hello World avec Node.js / Express</h2>

<p>Avant de pouvoir utiliser <em>Express</em>, nous devons initialiser un nouveau projet, de la même manière que l'épisode précédent, en utilisant la commande : <code>npm init -y</code></p>

<p>On peut ensuite écrire quelques lignes de codes pour créer notre première application express : ...</p>

<p><code>GET</code> est une <a href="https://developer.mozilla.org/fr/docs/Web/HTTP/M%C3%A9thode">méthode HTTP</a> utilisée par les navigateurs lorsque des pages Internet sont demandées au serveur. D'autres méthodes existent, les principales sont :</p>

<ul>
  <li><code>GET</code> pour récupérer une ressource ;</li>
  <li><code>POST</code> pour créer une nouvelle ressource ;</li>
  <li>...</li>
</ul>

La page contiendrait :

• des titres et sous-titres dans des balises <h1>, <h2> et <h3> ;
• des paragraphes avec des balises <p> ;
• du code dans des balises <code> ;
• des liens dans des balises <a> ;
• des mots spécifiques dans des balises <em> ;
• des listes dans des balises <ul> avec des éléments dans des balises <li> .

Le code HTML pourrait ensuite être intégré à notre site et la page fonctionnerait très bien.

Cette façon d'écrire les articles et de réaliser les pages est cependant laborieuse, car l'article est « pollué » avec tout le formalisme du langage HTML et toutes les considérations techniques du langage, comme les balises ouvrantes et fermantes, les attributs, etc.

Il serait beaucoup plus agréable de pouvoir écrire les articles en écrivant du simple texte brut, comme on écrirait un article dans un bloc-note, en ne se souciant pas des balises, ni du langage HTML.

Cette méthode est possible en utilisant, par exemple, le langage Markdown.

Présentation du langage Markdown

Le langage Markdown permet d'écrire du texte riche et formaté en écrivant simplement du texte brut.

Cela permet, entre autres, de dissocier les considérations techniques du langage de destination du texte source.

Si on reprend l'exemple précédent écrit en HTML, on pourrait réécrire la même chose en utilisant le langage Markdown :

## Hello World avec Node.js / Express

Avant de pouvoir utiliser *Express*, nous devons initialiser un nouveau projet, de la même manière que l'épisode précédent, en utilisant la commande : `npm init -y`

On peut ensuite écrire quelques lignes de codes pour créer notre première application express : ...

`GET` est une [méthode HTTP](https://developer.mozilla.org/fr/docs/Web/HTTP/M%C3%A9thode) utilisée par les navigateurs lorsque des pages Internet sont demandées au serveur. D'autres méthodes existent, les principales sont :

- `GET` pour récupérer une ressource ;
- `POST` pour créer une nouvelle ressource ;
- ...

Les balises HTML ont été supprimées. A la place, on utilise le formalise beaucoup plus léger du langage Markdown :

• les titres commencent par le caractère dièse : ## Titre ;
• les paragraphes sont simplement des lignes de texte ;
• les liens sont entre crochets et parenthèses [Texte affiché](lien);
• les mots spécifiques sont entre étoiles : *Mot* ;
• les listes sont simplement du texte avec un tiret : - Item.

Il n'existe pas de référence universelle qui détaille toutes les balises utilisables dans Markdown, contrairement à HTML ou CSS ou un standard a été créé avec des règles communes pour tous.

Chaque éditeur propose sa propre implémentation avec son propre formalisme. Presque tous reprennent cependant les spécifications CommonMark, qui est la première implémentation de Markdown réalisée par le créateur de Markdown.

Le site de CommonMark¹ détaille les balises qu'il propose. On y retrouve les éléments présents plus hauts comme les titres, les liens, et les listes. On remarque aussi que des balises alternatives sont proposées. Un liste peut, par exemple, être écrite avec un tiret -, comme on l'a vu précedemment, par avec une étoile *.

D'autres implémentations existent.

Le sites pour développeur GitHub.com² propose, par exemple, sa propre implémentation. Il comprend l'ensemble du formalisme de CommonMark et ajoute quelques balises spécifiques comme des cases à cocher : - [] Item a cocher.

Les forums de discussion Reddit proposent aussi une implémentation de Markdown³. Il comprend aussi les principales balises de CommonMark plus quelques nouveautés, comme des textes barrés ou des spoilers.

Les serveurs de messagerie Discord proposent aussi une implémentation légère de Markdown⁴ et propose, par exemple, d'afficher un texte souligné avec deux caractères underscores _.

On pourrait aussi citer GitLab.com⁵ et probablement plein d'autres.

Ce qu'on peut retenir, c'est que le langage Markdown est beaucoup utilisé sur Internet, car il permet de formater du texte facilement, sans aucune connaissance du langage HTML.

Parseur Markdown vers HTML

Pour convertir un texte Markdown vers du code HTML, il faut utiliser un convertisseur.

Pour cette vidéo, je vais utiliser le convertir que j'ai écrit et que j'utilise dans mes projets : github.com/deskeen/markdown

Le convertisseur comprend la plupart des balises CommonMark traditionnelles, plus quelques spécifiques comme les textes barrés, les exposants, ou les notes de bas de page. Il a aussi l'avantage de permettre aux développeurs de personnaliser le code HTML de sortie, en y ajoutant des classes CSS particulières ou des attributs spécifiques.

J'utilise, par exemple, ce convertisseur sur eWatchers.org pour afficher les articles que j'écris. Cet article utilise, par exemple, le convertisseur pour afficher des titres, des liens, des listes, des citations, et des notes de bas page. Cet article affiche une vidéo, et cet article affiche un son.

Nous allons intégrer ce convertisseur à notre backend, que l'on a commencé à réaliser dans les vidéos précédentes, et créer des pages HTML à partir d'articles écrits en Markdown.

Générer des pages HTML à partir d'un texte Markdown

Comme l'indique [la documentation](https://github.com/deskeen/markdown, on peut ajouter le convertisseur à notre projet en ajoutant le paquet : npm install @deskeen/markdown

On peut ensuite ajouter une route à notre backend, qui acceptera en entrée le numéro de l'article et retourner le contenu de la page à l'internaute :

// Importer la logique de la page article
const genererArticle = require('./pages/article-get.js')

// Ecoute la méthode GET et la route '/article/{NOMBRE}'
app.get(/\/article\/(\d+)/, async(req, res) => {
  const articleId = parseInt(req.params[0], 10)

  const articleHtml = await genererArticle(articleId)

  res.send(articleHtml)
})

Pour la logique, on peut s'inspirer du code que l'on a écrit dans la vidéo précédente pour générer la page à partir du modèle et intégrer le convertisseur :

const { join } = require('path')

const { readFile } = require('fs')
const { promisify } = require('util')
const readFileAsync = promisify(readFile)

const parser = require('@deskeen/markdown')

const READ_OPTIONS = { encoding: 'UTF-8' }
const HTML_URL = 'C:/dev/youtube/blog/code/html'
const MARKDOWN_URL = 'C:/dev/youtube/blog/code/article'

const lireFichierHtml = file =>
  readFileAsync(join(HTML_URL, file), READ_OPTIONS)

const lireFichierMarkdown = numeroArticle =>
  readFileAsync(join(MARKDOWN_URL, `${numeroArticle}.md`), READ_OPTIONS)

module.exports = async numeroArticle => {
  // Récupérer le contenu au format Markdown qui correspond
  // au numéro de l'article
  const articleMarkdown = await lireFichierMarkdown(numeroArticle)

  // Convertir Markdown vers HTML
  const articleHtml = parser.parse(articleMarkdown).innerHTML

  // Récupérer le contenu HTML du modele et des éléments de la page
  const modeleHtml = await lireFichierHtml('modele.html')

  const pageHtml = modeleHtml
    .replace('{{EN-TETE}}', '<title>Article</title>')
    .replace('{{CORPS}}', articleHtml)

  // Retourner la page HTML
  return pageHtml
}

Nous reste plus qu'à ajouter les styles CSS qui vont bien pour formater correctement toutes les balises HTML générées par le convertisseur et le tour est joué.

Utilisation de Markdown dans vos projets

Le langage Markdown peut être pour réaliser des pages Internet, comme nous l'avons fait, mais peut aussi être utilisé pour permettre aux internautes de saisir simplement dans des commentaires ou des messages comme le propose GitHub, Reddit ou Discord et plein d'autres.

Je l'utilise personnellement dans mes projets, comme sur ce blog ou sur eWatchers.org, soit pour créer des articles avec du contenu riche, comme des vidéos, des sons, des images.

Vous pouvez peut-être aussi l'utiliser dans vos projets et y trouver une utilité.

Se familiariser avec Markdown

J'ai ajouté un éditeur en ligne pour se familiariser avec le langage Markdown. Il permet de voir le résultat HTML en temps réel et peut être utilisé pour tester du texte Markdown.

Note: Le prochain épisode est disponible ici et le précédent ici.