La structure des fichiers Markdown

Le Markdown n'est pas un langage de programmation, mais un langage de balisage léger qui permet de structurer des documents de texte, pour un usage web, sans écrire le moindre élément HTML. Il favorise la lisibilité et la sémantique, chaque balise Markdown sert à organiser l'information plutôt que de définir son style.

Dans ce guide, nous allons voir à quoi ressemble le Markdown dans un fichier et quelles sont les balises qui sont utilisées dans la documentation du MDN.

Comment le MDN a adopté le Markdown

Jusqu'en septembre 2021, les pages de la documentation étaient écrites en HTML. En juin 2021 et jusqu'en septembre de la même année ^(angl.), un grand chantier de conversion des pages a été réalisé pour utiliser le format Markdown.

Cela a eu pour objectif de fournir une syntaxe plus simple à lire et à écrire que l'éditeur « What You See Is What You Get (WYSIWYG) » du MediaWiki de l'époque.

Le changement a été opéré après la première action majeure qui a été annoncée en décembre 2020, avec l'arrivée de Yari, le moteur de la documentation qui est venu remplacer Kuma ^(angl.).

Différences entre HTML et Markdown

Une page HTML se structure de manière à comporter un titre, des éléments de métadonnées, et un contenu divisé en bloc. Ces blocs doivent être définis à chaque fois que vous écrivez une nouvelle ligne d'un paragraphe, un titre, etc.

HTML

<p class="summary">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec vulputate neque quam, nec viverra nulla hendrerit dignissim.</p>

<h2 id="my-title">Mon titre</h2>

<p>Je suis <em>une description</em> complète qui <strong>met en avant un contenu</strong> pour l'expliquer.</p>

Le Markdown vient alléger le processus en utilisant des balises simplifiées.

Markdown

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec vulputate neque quam, nec viverra nulla hendrerit dignissim.

## Mon titre

Je suis _une description_ complète qui **met en avant un contenu** pour l'expliquer.

Cette grande différence nous permet d'obtenir un rendu identique, pour une écriture claire et rapide de la page à modifier.

Le balisage Markdown

Les tableaux suivants présentent les différentes balises Markdown (et GitHub Flavored Markdown, qui est une version étendue de Markdown avec des fonctionnalités personnalisées) utilisées dans la documentation du MDN.

Le Markdown classique

Les éléments présentés dans ce tableau, sont les éléments qui composent la base du Markdown et qui représentent des éléments HTML communs, tels que les titres, les listes, le gras, le code, etc.

Les différentes balises Markdown utilisées dans la documentation

Balise	Type	Équivalent en HTML	Exemple en Markdown
#	Titres	<h2>Titre</h2>	## Titre de niveau 2
**	Gras	<strong>Texte</strong>	**Texte en gras**
_	Italique	<em>Texte</em>	_Texte en italique_
-	Liste à puces	<ul> <li>Élément de liste</li> </ul>	- Élément de liste
1.	Liste ordonnée	<ol> <li>Premier élément</li> </ol>	1. Premier élément
[texte](url)	Lien	<a href="url">Texte</a>	[Texte du lien](https://example.com)
	Image	<img src="url" alt="Texte">	
`	Code en ligne	<code>code</code>	`code en ligne`
```	Bloc de code	<pre class="language-markdown"><code>code</code></pre>	```markdown code ```
>	Bloc de citation	<blockquote> <p>Texte</p> </blockquote>	> Texte de la citation

Le Markdown étendu

Ces éléments ne sont pas standard au Markdown, mais sont des extensions qui sont créés par les moteurs de rendu qui étendent le Markdown pour fournir des fonctionnalités complémentaires.

Les différentes balises GitHub Flavored Markdown utilisées dans la documentation

Balise	Type	Équivalent en HTML	Exemple en Markdown
- :	Définitions	<dl> <dt>Terme</dt> <dd>Définition</dd> </dl>	- Terme - : Définition
> [!NOTE] > [!WARNING] > [!CALLOUT]	Alertes	N'est pas un élément HTML	> [!NOTE] > Ceci est une note
| | | - |	Tableaux	<table> <thead> <tr> <th>En-tête 1</th> <th>En-tête 2</th> </tr> </thead> <tbody> <tr> <td>Donnée 1</td> <td>Donnée 2</td> </tr> </tbody> </table>	| En-tête 1 | En-tête 2 | | --------- | --------- | | Donnée 1 | Donnée 2 |

Résumé

Nous avons vu que les pages utilisent un format allégé nommé Markdown et les différentes balises que nous utilisons sur le MDN. Vous pouvez utiliser ce guide comme référence explicative des balises Markdown que vous croiserez dans la documentation. Dans le guide suivant, nous verrons comment fonctionne la « Page de garde » (Front Matter en anglais) des fichiers Markdown du MDN, représentant les métadonnées d'une page.