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 :
| Fonction | Syntaxe | Exemple |
|---|---|---|
| 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ée | 1. item | 1. 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
- [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.
> [!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 :
> [!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
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
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
-
Lien vers un titre :
[Link to the "Footnotes" section](#3-footnotes) -
Lien vers un paragraphe personnalisé :
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
-
Il s'agit d'une note de bas de page pour la démonstration. ↩
