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.

Objectif

Markdown vise à offrir une écriture fluide, naturelle et lisible en texte brut, tout en pouvant être convertie 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 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.
  • Il n'existe pas de standard unique, plusieurs variantes (ou "flavors") existent, telles que :
    • GitHub Flavored Markdown (GFM)
    • GitLab Flavored Markdown
    • CommonMark (tentative de normalisation du langage)

➡️ GitHub Markdown Cheatsheet

➡️ GitLab Flavored Markdown

🎁 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 hashtags (#):

- `# 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 hashtags (#):

  • # 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.