Tutoriel : Ecrire du Code en Markdown

Qu’est-ce que le Markdown ?

Le Markdown est un langage de balisage léger, souvent comparé à un HTML simplifié, conçu pour être facile à écrire et à lire.

Il permet de structurer des documents de manière simple, sans avoir à maîtriser des balises complexes.

Créé par John Gruber en 2004, il a rapidement gagné en popularité en raison de sa simplicité et de son efficacité.

En Markdown, le but est de rendre le texte plus lisible dans sa forme brute tout en permettant d’ajouter des éléments de formatage élémentaires comme des titres, des listes, des liens, et, bien sûr, du code.

Le code Markdown est écrit au sein d’un fichier portant l’extension .md. En voici un petit extrait !

Le **Markdown**, c'est :
- Simple
- Efficace

Et voici son équivalent HTML :

<p>Le <strong>Markdown</strong>, c'est :</p>
<ul>
    <li>Simple</li>
    <li>Efficace</li>
</ul>

L’utilisation du Markdown s’étend à des outils comme GitHub, Reddit ou même dans des applications de messagerie comme Discord ou ChatGPT, où il permet de formater rapidement du texte et du code.

Comparatif : HTML vs Markdown

Voici un tableau de correspondance entre la syntaxe du Markdown et du HTML pour quelques éléments de base comme la mise en gras/italique, les liens, les listes, les citations et images :

Le Markdown est très pratique pour le formatage rapide, mais il présente des limites lorsqu’il s’agit de gérer des structures et contenus plus complexes (éléments de formulaires, médias…).

Par exemple, un lien en Markdown ne prend pas en charge autant d’options que les attributs HTML (target, aria et rel n’existent pas).

Formater du code en Markdown

Grâce à sa simplicité et sa flexibilité, le Markdown est devenu un choix incontournable pour les développeurs, les rédacteurs techniques et même les utilisateurs occasionnels de plateformes de communication.

Alors si les profils d’usagers du Markdown sont pour la plupart des techniciens, être capable d’écrire des extraits de code (aussi appelés code snippets) est un besoin essentiel !

Mais une question se pose… comment écrire et partager du code en Markdown ? 🤔

Voici un guide rapide pour bien partager du code en Markdown, qu’il s’agisse de petites portions de code dans une phrase (code « inline ») ou de blocs de code plus longs (les fameux « codeblocks »).

Code inline en Markdown

Le code inline est parfait pour insérer des petites portions de code directement dans le texte, sans interrompre le flux de la lecture.

Par exemple, si vous souhaitez insérer un petit extrait de code comme une fonction JavaScript dans une phrase, vous pouvez le faire en utilisant des backticks (`…`) comme délimiteurs avant et après le code.

`console.log('Hello World!')`

On obtient ainsi à l’affichage l’extrait de code suivant 👉 console.log('Hello World!')

Si les extraits de code en ligne s’avèrent très utiles pour formater proprement un extrait de code indiqué dans le flux d’une phrase normale, ils présentent des limites pour écrire et/ou partager des extraits de code complets, généralement composés de plusieurs lignes.

Nous aurons alors besoin de codeblock.

Bloc de code (codeblock) en Markdown

Pour afficher un bloc de code, on utilise toujours les backticks comme délimiteurs, mais cette fois-ci, au nombre de 3.

‎```javascript
function hello() {
   return 'Hello World!'; 
}
‎```

Bien qu’optionnel, il est recommandé de spécifier le langage de l’extrait de code (ici javascript) à la suite des trois backticks pour activer la coloration syntaxique, ce qui améliore la lisibilité et la compréhension du code.

On obtient ainsi à l’affichage l’extrait de code suivant 👇

function hello() {
   return 'Hello World!'; 
}