Retour au blog
Articles

Cinq syntaxes GitHub Markdown utiles

Des exemples de tâches, alertes, notes et ancres pour un README plus lisible.

Un README se contente souvent de titres, de listes et de liens. Pour signaler un avertissement, suivre des tâches ou ajouter des précisions, GitHub propose d'autres éléments Markdown. En voici cinq, avec des exemples à essayer.

Syntaxe de base

Commençons par un rappel des formes courantes :

FonctionSyntaxeExemple
Titre# Heading 1, ## Heading 2, ### Heading 3# Heading 1, ## Heading 2, ### Heading 3
Gras**text** ou __text__**bold text**
Italique*text* ou _text_*italic text*
Barré~~text~~~~strikethrough text~~
Citation> blockquote> This is a quote
Code en ligne`code``print("Hello, World!")`
Bloc de code```print("Code block")
Liste non ordonnée- item ou * item- unordered 1 ou * unordered 2
Liste ordonnée1. item1. ordered 1
2. ordered 2
Hyperlien[link text](URL)[GitHub](https://github.com)
Règle horizontale--- ou ***--- ou ***
Emoji:emoji_code::smile:, :thumbsup:

Les exemples suivants vont un peu plus loin, tout en restant faciles à ajouter à un document.

1. Listes de tâches

Les listes de tâches montrent les étapes d'un projet sous forme de cases à cocher.

Elles distinguent les tâches terminées de celles qui restent à faire, notamment dans les projets collaboratifs.

Exemple d'écriture

Code
- [x] Complete initial project setup
- [ ] Write user requirements document
- [ ] Integrate front-end and back-end code

[x] marque une tâche terminée ; [ ] désigne une tâche en attente.

Dans les issues et les pull requests GitHub, les cases peuvent être cochées directement au fil du travail.

Sortie visuelle

  • Configuration initiale complète du projet
  • Écrire le document sur les besoins de l'utilisateur
  • Intégrer le code front-end et back-end

2. Alertes

Les alertes mettent en évidence une information au moyen d'un encadré et d'une icône.

Cette syntaxe est propre à GitHub et n'appartient pas au Markdown de base.

Exemple d'écriture

GitHub offre cinq types d'alertes : NOTE, TIP, IMPORTANT, WARNING, et CAUTION.

markdown
> [!NOTE]
> Useful information for skimming users.

> [!TIP]
> Tips for better or easier implementation.

> [!IMPORTANT]
> Essential details for achieving a goal.

> [!WARNING]
> Critical info requiring immediate attention.

> [!CAUTION]
> Warnings about risks or negative outcomes.

Pour une alerte sur plusieurs lignes, ajoutez > au début de chaque ligne :

markdown
> [!TIP]
> This is a tip.
>
> Here is another tip.

Sortie visuelle

Voici le résultat sur GitHub :

3. Notes de bas de page

Les notes de bas de page permettent d'ajouter une source ou un détail sans interrompre la lecture.

GitHub crée un lien entre l'appel de note dans le texte et sa définition plus bas.

Exemple d'écriture

markdown
In this step, we use a special feature[^1].

[^1]: Detailed notes or external links can be added here.

Au rendu, un numéro en exposant mène à la note correspondante.

Sortie visuelle

Cette phrase contient une note de bas de page1. Cliquez sur son numéro pour la consulter.

4. Échapper les caractères spéciaux

Pour afficher un astérisque ou un autre caractère spécial tel quel, placez une barre oblique inverse devant lui.

Exemple d'écriture

markdown
To display a `*` symbol, add a backslash: \*

Let's rename \*our-new-project\* to \*our-old-project\*.

Sortie visuelle

Pour afficher un astérisque : *

Le nom *ancien-projet* reste entouré d'astérisques visibles.

5. Ancres personnalisées

Les titres génèrent des ancres automatiquement. Pour créer un lien vers un autre passage, on peut aussi ajouter une ancre HTML à la main.

Exemple d'écriture

  1. Lien vers un titre :

    markdown
    [Link to the "Footnotes" section](#3-footnotes)
    
  2. Lien vers un paragraphe personnalisé :

    markdown
    This is a special paragraph for internal linking.
    
    [Link to this paragraph](#my-custom-anchor)
    

Sortie visuelle

Cliquez ici pour le lien vers la section « Notes »


Il s'agit d'un paragraphe spécial pour les liens internes.

Pour conclure

Ces éléments facilitent la lecture lorsqu'ils répondent à un besoin précis. Un README n'a pas besoin de tous les effets disponibles.

Références

Notes

  1. Il s'agit d'une note de bas de page pour la démonstration. ↩