Qu’est-ce que Markdown ?
Markdown est un langage de balisage qui offre une approche allégée de la modification de contenu en mettant les créateurs de contenu à l’abri de la surcharge du langage HTML. Même si le code HTML est parfait pour le rendu de contenu tel qu’il a été conçu, il occupe beaucoup d’espace et peut être difficile à exploiter, même à petites doses. Markdown offre un excellent compromis entre la puissance de la syntaxe HTML pour la description du contenu et la facilité du texte brut pour la modification.
Dans cette unité, nous allons aborder la structure et la syntaxe de Markdown. Nous couvrirons également les fonctionnalités GFM (GitHub-Flavored Markdown), qui sont des extensions de syntaxe vous permettant d’intégrer des fonctionnalités GitHub dans du contenu.
Notes
Cette unité est destinée à vous offrir un aperçu de Markdown. Pour un examen plus approfondi, reportez-vous aux articles Description de la syntaxe Markdown et Spécification de la syntaxe GitHub Markdown dans l’unité Résumé de ce module.
Mettre en évidence le texte
La partie la plus importante de toute communication sur GitHub est généralement le texte lui-même, mais comment montrer que certaines parties du texte sont plus importantes que d’autres ?
Appliquer le format italique au texte est aussi facile que de placer le texte cible entre deux astérisques (*) ou deux traits de soulignement (_). Veillez simplement à utiliser le même caractère au début et à la fin de l’accentuation. Soyez attentif à la façon dont vous combinez les astérisques et les traits de soulignement. Voici quelques exemples :
This is *italic* text.
This is also _italic_ text.
This is italic text. C’est aussi du texte en italique.
Créez du texte en gras en utilisant deux astérisques (**) ou deux traits de soulignement (__).
This is **bold** text.
This is also __bold__ text.
This is bold text. C’est aussi du texte en gras.
Vous pouvez également combiner des mises en relief.
_This is **italic and bold** text_ using a single underscore for italic and double asterisks for bold.
__This is bold and *italic* text__ using double underscores for bold and single asterisks for italic.
C’est un texte en italique et en gras qui utilise un trait de soulignement unique pour l’italique et deux astérisques pour le gras. C’est un texte en gras et en italique qui utilise deux traits de soulignement pour le gras et un astérisque unique pour l’italique.
Pour utiliser un astérisque littéral, faites-le précéder d’un caractère d’échappement, à savoir une barre oblique inverse (\) dans GFM. Dans cet exemple de sortie, les traits de soulignement et les astérisques sont affichés.
\_This is all \*\*plain\*\* text\_.
_This is all **plain** text_.
Déclarer des en-têtes
HTML fournit des titres de contenu, comme par exemple la balise <h1>. Dans Markdown, cette fonction est prise en charge par le biais du symbole #. Utilisez juste un # pour chaque niveau de titre de 1 à 6.
###### This is H6 text
This is H6 text
Lier à des images et des sites
Les liens d’image et de site utilisent une syntaxe similaire.
[Link to Microsoft Training](/training)
Créer des listes
Vous pouvez définir des listes triées ou non triées. Vous pouvez également définir des éléments imbriqués à l’aide de la mise en retrait.
- Les listes triées commencent par des nombres.
- Les listes non triées peuvent utiliser des astérisques ou des tirets (
-).
Voici le balisage Markdown pour une liste triée :
1. First
1. Second
1. Third
Résultat :
- First
- Second
- Third
Voici le balisage Markdown pour une liste non triée :
- First
- Nested
- Second
- Third
- Premier(s)
- Nested
- Second
- Third
Développer des tableaux
Vous pouvez construire des tables à l’aide d’une combinaison de barres verticales (|) pour les sauts de colonne, et de tirets (-) pour désigner la ligne précédente comme en-tête.
First|Second
-|-
1|2
3|4
First Second 1 2 3 4
Texte de guillemet
Vous pouvez créer des blocs de citation à l’aide du caractère supérieur à (>).
> This is quoted text.
This is quoted text.
Remplir des espaces avec du code HTML inline
Si votre scénario HTML n’est pas pris en charge par Markdown, vous pouvez utiliser ce code HTML inline.
Here is a<br />line break
Here is a
line break
Travailler avec du code
Par défaut, Markdown prend en charge les blocs de code inline délimités par le caractère de guillemet inversé (`). Quand le texte est décoré avec ce caractère, il est restitué en tant que code.
This is `code`.
This is
code.
Si vous avez un segment de code répartis sur plusieurs lignes, vous pouvez utiliser trois guillemets inversés (```) avant et après pour créer un bloc de code délimité.
```markdown
var first = 1;
var second = 2;
var sum = first + second;
```
var first = 1; var second = 2; var sum = first + second;
La syntaxe GitHub Markdown étend cette prise en charge avec la mise en évidence de la syntaxe des langages populaires. Spécifiez simplement le langage dans la première séquence de guillemets inversés.
```javascript
var first = 1;
var second = 2;
var sum = first + second;
```
var first = 1; var second = 2; var sum = first + second;
Références croisées des problèmes et demandes de tirage (pull requests)
La syntaxe GitHub Markdown prend en charge différents formats de code court pour faciliter la liaison aux problèmes et demandes de tirage (pull requests). Pour ce faire, le plus simple est d’utiliser le format #ID, tel que #3602. GitHub ajuste automatiquement les liaisons plus longues à ce format si vous les collez. Vous pouvez également suivre des conventions supplémentaires, par exemple, si vous utilisez d’autres outils ou souhaitez spécifier d’autres projets/branches.
| Type de référence | Référence brute | Lien court |
|---|---|---|
| URL de problème ou de demande de tirage (pull request) | https://github.com/desktop/desktop/pull/3602 |
#3602 |
# et numéro de problème ou de demande de tirage (pull request) |
#3602 | #3602 |
GH- et numéro de problème ou de demande de tirage (pull request) |
GH-3602 | GH-3602 |
Username/Repository# et numéro de problème ou de demande de tirage (pull request) |
desktop/desktop#3602 | desktop/desktop#3602 |
Pour plus d’informations, consultez l’article Références et URL liées automatiquement dans l’unité Résumé de ce module.
Validations spécifiques aux liens
Vous pouvez créer un lien vers un commit en collant son ID, ou simplement en utilisant son algorithme de hachage sécurisé (SHA).
| Type de référence | Référence brute | Lien court |
|---|---|---|
| URL de commit | https://github.com/desktop/desktop/commit/ | |
| 8304e9c271a5e5ab4fda797304cd7bcca7158c87 | 8304e9c | |
| SHA | 8304e9c271a5e5ab4fda797304cd7bcca7158c87 | 8304e9c |
| User@SHA | desktop@8304e9c271a5e5ab4fda797304cd7bcca7158c87 | desktop@8304e9c |
| Username/Repository@SHA | desktop/desktop@8304e9c271a5e5ab4fda797304cd7bcca7158c87 | desktop/desktop@8304e9c |
Mentionner des utilisateurs et des équipes
Le fait d’entrer un symbole @, suivi d’un nom d’utilisateur GitHub, envoie une notification à cette personne au sujet du commentaire. C’est ce que l’on appelle une « @mention », car vous mentionnez la personne. Vous pouvez également utiliser @mention pour désigner des équipes au sein d’une organisation.
@githubteacher
Suivre les listes des tâches
Vous pouvez créer des listes de tâches dans des problèmes ou des demandes de tirage (pull requests) en utilisant la syntaxe suivante. Elles peuvent être efficaces pour suivre la progression quand elles sont utilisées dans le corps d’un problème ou d’une demande de tirage.
- [x] First task
- [x] Second task
- [ ] Third task
Commandes slash
Les commandes à barre oblique peuvent vous faire gagner du temps en réduisant la saisie requise pour créer du code Markdown complexe.
Vous pouvez utiliser les commandes à barre oblique dans n’importe quel champ de description ou de commentaire dans les problèmes, les demandes de tirage ou les discussions où elles sont prises en charge.
| Commande | Description |
|---|---|
/code |
Insère un bloc de code Markdown. Vous choisissez le langage. |
/details |
Insère une zone de détails réductible. Vous choisissez le titre et le contenu. |
/saved-replies |
Insère une réponse enregistrée. Vous choisissez parmi les réponses enregistrées pour votre compte d’utilisateur. Si vous ajoutez %cursor% à votre réponse enregistrée, la commande à barre oblique place le curseur à cet emplacement. |
/table |
Insère un tableau Markdown. Vous choisissez le nombre de colonnes et de lignes. |
/tasklist |
Insère une liste de tâches. Cette commande à barre oblique fonctionne uniquement dans une description de problème. |
/template |
Affiche tous les modèles dans le dépôt. Vous choisissez le modèle à insérer. Cette commande à barre oblique fonctionne pour les modèles de problème et un modèle de demande de tirage. |