Guide Markdown

Qu'est-ce que Markdown ?

Markdown est un langage de balisage léger que vous pouvez utiliser pour ajouter des éléments de formatage aux documents de texte brut. Il vous permet de créer du texte formaté en utilisant une syntaxe simple et facile à lire qui peut être convertie en HTML et d'autres formats.

Pensez à Markdown comme un moyen d'écrire des documents formatés sans avoir besoin de traitements de texte complexes. Vous ajoutez simplement des caractères spéciaux au texte brut pour indiquer le formatage comme gras, italique, ou code.

Pourquoi utiliser Markdown ?

Markdown est incroyablement simple et facile à apprendre. Vous pouvez maîtriser les bases en seulement 10 minutes. Les symboles de formatage sont intuitifs - des astérisques pour l'emphase, des dièses pour les titres. Vous tapez simplement et ajoutez des symboles simples pour formater votre texte.

Markdown fonctionne sur n'importe quelle plateforme et n'importe quel éditeur de texte. Puisque les fichiers sont en texte brut, ils seront toujours lisibles, même dans des décennies. Les fichiers sont légers et se chargent rapidement.

Markdown bénéficie d'un large support sur les plateformes. GitHub, Reddit, Discord et Slack utilisent tous Markdown. Des applications populaires comme Obsidian, Notion et VS Code le supportent nativement. Cela le rend parfait pour la documentation, la prise de notes et le contenu web.

Markdown fonctionne parfaitement avec les systèmes de contrôle de version comme Git. Vous pouvez vous concentrer sur le contenu sans distractions de formatage. La collaboration en équipe est plus facile car tout le monde peut éditer les fichiers sans logiciel spécialisé.

Histoire du développement de Markdown

Le commencement : Markdown Vanilla (2004)

Markdown a été créé à l'origine par John Gruber en 2004, avec une contribution significative d'Aaron Swartz. Gruber l'a conçu comme un moyen simple d'écrire en utilisant un format de texte brut facile à lire et à écrire qui pourrait être converti en HTML structurellement valide. C'est le "noyau" que John Gruber a initialement conçu et implémenté, contenant la syntaxe de formatage la plus basique - ce que nous appelons la "saveur vanilla de base".

Syntaxe de base (Markdown Vanilla inclut) :

  • •
    En-têtes : Utilisez le symbole # (# En-tête)

  • •
    Emphase :

  • •
    Italique : Utilisez * ou _ pour entourer le texte (*italique* ou _italique_)
  • •
    Gras : Utilisez ** ou __ pour entourer le texte (**gras** ou __gras__)

  • •
    Listes :

  • •
    Listes non ordonnées : Utilisez *, -, ou + (- élément)
  • •
    Listes ordonnées : Utilisez des numéros avec des points (1. élément)
  • •
    Liens : Utilisez [texte du lien](adresse du lien)
  • •
    Images : Utilisez ![description de l'image](adresse de l'image)

  • •
    Blocs de code : Indentez avec des espaces (généralement 4 espaces ou 1 Tab)

  • •
    Citations : Utilisez le symbole > (> Ceci est une citation)
  • •
    Règles horizontales : Utilisez --- ou ***

Le problème : Implémentations incohérentes

Cependant, Markdown Vanilla manquait d'une spécification stricte et formelle. Cela a conduit à un comportement incohérent entre différents analyseurs Markdown lors de la gestion des cas limites.

Gestion des espaces blancs : Par exemple, dans les éléments de liste, combien d'espaces d'indentation comptent comme une sous-liste ? Est-ce 2 espaces, 3 espaces, ou 4 espaces ? Différents analyseurs peuvent avoir des jugements différents.

Traitement des sauts de ligne : Dans certaines situations, un saut de ligne normal (\n) doit-il être analysé comme une balise
(saut de ligne), ou simplement traité comme un espace dans le texte ? Cela peut aussi varier selon l'analyseur.

Utilisation mixte HTML : Markdown permet l'intégration de HTML. Cependant, dans certaines structures HTML complexes, la façon dont les analyseurs Markdown gèrent la syntaxe Markdown à l'intérieur présente aussi des zones ambiguës.

La solution : CommonMark (2014)

En septembre 2014, CommonMark a été introduit pour résoudre ces problèmes d'incohérence. Dirigé par John MacFarlane, il fournit une spécification rigoureuse pour Markdown.

CommonMark fournit une spécification précise où chaque cas limite est clairement défini. Il inclut une suite de tests complète avec plus de 600 cas de test pour assurer la cohérence entre les implémentations. La spécification fournit une implémentation de référence qui sert de standard pour que d'autres analyseurs la suivent. Elle maintient la rétrocompatibilité avec la plupart des documents Markdown existants tout en garantissant une analyse non ambiguë où la même entrée produit toujours la même sortie sur tous les analyseurs conformes.

Saveurs étendues et fonctionnalités supplémentaires

Comme les utilisateurs avaient différents besoins, diverses saveurs étendues de Markdown ont émergé pour répondre à des exigences spécifiques.

Syntaxe supplémentaire de GitHub Flavored Markdown (GFM) :

  • •
    Tableaux : Utilisez la syntaxe de barre verticale pour créer des tableaux
  | En-tête 1 | En-tête 2 | En-tête 3 |
  |-----------|-----------|-----------|
  | Cellule 1 | Cellule 2 | Cellule 3 |
  | Cellule 4 | Cellule 5 | Cellule 6 |
  • •
    Texte barré : Utilisez ~~ pour entourer le texte (~~texte supprimé~~)

  • •
    Listes de tâches : Créez des cases à cocher interactives

  - [x] Tâche terminée
  - [ ] Tâche incomplète
  • •
    Blocs de code délimités : Utilisez des triples backticks avec spécification de langue
  ```javascript
  function hello() {
    console.log("Hello World!");
  }
  ```
  • •
    Liaison automatique : Les URLs et adresses email deviennent cliquables automatiquement

Autres extensions populaires :

  • •
    Notes de bas de page : Utilisez la syntaxe [^1] pour l'écriture académique
  Ceci est une phrase avec une note de bas de page[^1].
  [^1]: Ceci est le contenu de la note de bas de page.

Résultat : Ceci est une phrase avec une note de bas de page¹.

  • •
    Expressions mathématiques : Utilisez $E=mc^2$ pour les documents scientifiques
  • •
    Raccourcis emoji : Utilisez :smile: devient 😊

  • •
    Listes de définition : Pour les glossaires et la documentation technique

  Terme 1
  : Définition du terme 1
  
  Terme 2
  : Définition du terme 2
  : Autre définition du terme 2

Résultat : Crée des listes formatées avec des termes mis en évidence et des définitions indentées

Comment ça marche ?

Markdown suit un flux de travail simple en trois étapes :

Étape 1 : Créer un fichier Markdown

D'abord, vous créez un fichier de texte brut avec une extension .md ou .markdown en utilisant n'importe quel éditeur de texte. Vous écrivez votre contenu en utilisant des symboles de formatage simples :

Étape 2 : Traitement avec les outils Markdown

Votre fichier .md est ensuite traité par des outils de conversion Markdown ou des processeurs. Ces outils lisent votre fichier Markdown et le convertissent au format de sortie désiré.

Étape 3 : Sortie vers divers formats

Le processeur Markdown peut convertir votre fichier vers plusieurs formats :

Pour l'affichage web :

  • •
    Convertit en HTML pour les sites web, blogs et applications web

  • •
    Affiche le contenu formaté dans les navigateurs avec un style approprié

Pour les documents :

  • •
    Convertit en PDF pour les documents imprimables et rapports

  • •
    Génère des documents Word (.docx) pour un usage bureautique
  • •
    Crée du LaTeX pour les articles académiques et publications

Pour la publication :

  • •
    Génère des livres électroniques (format EPUB)

  • •
    Crée des diapositives de présentation
  • •
    Produit des sites web de documentation

Ce flux de travail signifie que vous écrivez une fois en Markdown, puis utilisez différents outils pour convertir votre contenu vers n'importe quel format dont vous avez besoin - que ce soit pour l'affichage sur un site web, l'impression en PDF, ou le partage comme document.

Ressources supplémentaires

Documentation essentielle

  • •
    Documentation Markdown de John Gruber : Le guide original écrit par le créateur de Markdown. Lecture essentielle pour comprendre la philosophie et la syntaxe de base.

  • •
    Wikipedia - Markdown : Aperçu complet de l'histoire, des variations et des détails techniques de Markdown.

  • •
    Guide Markdown : Un guide complet et convivial pour débutants avec des exemples et les meilleures pratiques pour tous les niveaux de compétence.