Aller au contenu

Markdown

Markdown est un langage de balisage léger conçu pour formater du texte de manière simple, lisible et compatible avec le web.

Il a été créé en 2004 par John Gruber, avec la collaboration d'Aaron Swartz, dans le but de permettre à tout utilisateur d'écrire des documents formatés sans devoir maîtriser le HTML.

Source : Daring Fireball - Markdown (John Gruber)

Objectif

Markdown vise à offrir une écriture fluide, naturelle et lisible en texte brut. Le texte peut ensuite être converti facilement en HTML, PDF ou d'autres formats.

Ainsi, un même fichier peut être lu directement dans un éditeur texte ou affiché de manière stylisée sur une plateforme web.

Principes de base

  • Un fichier Markdown est un simple fichier texte brut, portant généralement l'extension .md.
  • La mise en forme s'effectue à l'aide de symboles simples (comme *, _, #, >, etc.) pour indiquer les titres, la mise en gras, les listes, les liens, ou les citations.
  • Markdown est indépendant de la plateforme : il fonctionne sur GitHub, GitLab, Reddit, Discord, Notion, Trello, Obsidian, etc.
  • Il peut être converti en HTML, PDF, ou autres formats à l'aide d'outils comme pandoc, grip ou markdown-it. Ce site de cours est lui-même écrit en Markdown et converti en pages web par MkDocs.
  • Il n'existe pas de standard unique : la description d'origine de John Gruber laisse des cas ambigus, si bien que plusieurs variantes (ou « flavors ») sont apparues, telles que :
    • CommonMark : spécification précise et sans ambiguïté, qui sert de base aux deux variantes suivantes
    • GitHub Flavored Markdown (GFM) : CommonMark + extensions de GitHub (tableaux, listes de tâches, texte barré…)
    • GitLab Flavored Markdown (GLFM) : CommonMark + extensions de GFM et de GitLab

Sources :

🎁 Bonus pour ceux qui utilisent Discord : Markdown Text 101

Utilisations fréquentes

Markdown est omniprésent dans les outils de développement et de documentation.

Il est utilisé notamment pour :

  • README.md → Description du projet (sur GitHub, GitLab, etc.)
  • CHANGELOG.md → Journal des modifications
  • CONTRIBUTING.md → Guide de contribution à un projet
  • Commentaires sur GitHub, GitLab, ou Stack Overflow
  • Documentation technique dans les wikis de projets
  • Plateformes sociales : Discord, Reddit, etc.

Tip

Markdown est à la documentation ce que Git est au code : simple, universel et indispensable.

📄 Exemple

# My Markdown Document

This is an example of a document written in Markdown. Markdown is a lightweight
markup language that allows you to easily format text.
Here are some basic elements:

## Headings

You can create headings using one or more hash symbols (#):

- `# Level 1 Heading` for a main heading.
- `## Level 2 Heading` for a subheading.
- `### Level 3 Heading` for a sub-subheading, and so on.

## Lists

Bulleted lists are easy to create:

- Item 1
- Item 2
- Item 3

Numbered lists are also supported:

1. First item
2. Second item
3. Third item

## Text Formatting

You can make text _italic_ by enclosing it in single asterisks or underscores,
like `*italic*` or `_italic_`. For **bold** text, use double asterisks or
underscores, like `**bold**` or `__bold__`.

## Links

Hypertext links are created using the following syntax: `[link text](URL)`.

For example, here's a link to [OpenAI](https://www.openai.com/).

## Images

Images can be inserted in the same way as links, using `![alt text](image URL)`.

Here's an image of One Piece:
![One Piece](https://example.com/one-piece.png)

That's it for this example. Markdown is a quick and efficient way to write
structured content for the web.

🖥️ Rendu

My Markdown Document

This is an example of a document written in Markdown. Markdown is a lightweight markup language that allows you to easily format text. Here are some basic elements:

Headings

You can create headings using one or more hash symbols (#):

  • # Level 1 Heading for a main heading.
  • ## Level 2 Heading for a subheading.
  • ### Level 3 Heading for a sub-subheading, and so on.

Lists

Bulleted lists are easy to create:

  • Item 1
  • Item 2
  • Item 3

Numbered lists are also supported:

  1. First item
  2. Second item
  3. Third item

Text Formatting

You can make text italic by enclosing it in single asterisks or underscores, like *italic* or _italic_. For bold text, use double asterisks or underscores, like **bold** or __bold__.

Hypertext links are created using the following syntax: [link text](URL).

For example, here's a link to OpenAI.

Images

Images can be inserted in the same way as links, using ![alt text](image URL).

Here's an image of One Piece: One Piece

That's it for this example. Markdown is a quick and efficient way to write structured content for the web.