GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown (GFM) est la version améliorée de Markdown par GitHub avec des fonctionnalités supplémentaires conçues spécifiquement pour le développement logiciel et la collaboration. Ce guide couvre toutes les extensions de syntaxe spéciales disponibles sur GitHub.

Qu'est-ce que GitHub Flavored Markdown (GFM) ?

GitHub Flavored Markdown étend la syntaxe de base de Markdown avec des fonctionnalités qui le rendent plus utile pour :

• La documentation (READMEs, wikis)
• Le suivi des issues
• Les pull requests
• La révision de code
• La gestion de projet

Fonctionnalités Principales du GFM

1. Blocs de Code Délimités

GFM prend en charge les blocs de code délimités avec coloration syntaxique spécifique au langage :

```javascript
function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // Output: 15
```

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // Output: 15

2. Coloration Syntaxique

GitHub prend en charge la coloration syntaxique pour des centaines de langages. Certains courants incluent :

# Script Bash
echo "Hello GitHub!"

# Script Python
def greet(name):
    return f"Hello, {name}!"

// Code Java
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello GitHub!");
    }
}

3. Listes de Tâches

Créez des listes de tâches interactives avec des cases à cocher :

- [x] Terminer l'authentification utilisateur
- [x] Implémenter les endpoints API
- [ ] Écrire les tests unitaires
  - [ ] Tests backend
  - [ ] Tests frontend
- [ ] Déployer en production

• [x] Terminer l'authentification utilisateur
• [x] Implémenter les endpoints API
• [ ] Écrire les tests unitaires
  • [ ] Tests backend
  • [ ] Tests frontend
• [ ] Déployer en production

4. Tableaux

GFM fournit une syntaxe simple pour créer des tableaux :

| Fonctionnalité    | Pris en charge | Description                     |
|-------------------|----------------|---------------------------------|
| Fenced Code       | ✅             | Coloration spécifique au langage|
| Task Lists        | ✅             | Cases à cocher interactives     |
| Tables            | ✅             | Affichage de données structurées|
| Mentions          | ✅             | Notifications utilisateur/équipe|
| Emoji             | ✅             | Expressions visuelles           |

Fonctionnalité	Pris en charge	Description
Fenced Code	✅	Coloration spécifique au langage
Task Lists	✅	Cases à cocher interactives
Tables	✅	Affichage de données structurées
Mentions	✅	Notifications utilisateur/équipe
Emoji	✅	Expressions visuelles

5. Mentions

Mentionnez des utilisateurs ou des équipes pour les notifier :

@username - Mentionner un utilisateur spécifique
@team-name - Mentionner une équipe

6. Emoji

Ajoutez des emoji en utilisant des codes courts :

:smile: - 😊
:thumbsup: - 👍
:heart: - ❤️
:rocket: - 🚀
:warning: - ⚠️

😄 - 😊 👍 - 👍 ❤️ - ❤️ 🚀 - 🚀 ⚠️ - ⚠️

7. Liaison Automatique

GFM lie automatiquement certains types de contenu :

Numéros d'Issue et de Pull Request

#123 - Lie vers l'issue 123
PR #456 - Lie vers la pull request 456

Hashes SHA

a1b2c3d - Lie vers le commit avec ce SHA

Mentions d'Utilisateur dans les Issues/PRs

@username - Lie automatiquement vers le profil de l'utilisateur

URLs

https://github.com - Devient automatiquement un lien

8. Texte Barré

GFM prend en charge le texte barré :

~~Ce texte est barré~~

Ce texte est barré

9. Références de Lien Automatique

GFM crée automatiquement des liens pour :

• Les URLs HTTP/HTTPS
• Les adresses e-mail
• Les numéros d'issue/PR GitHub
• Les SHA de commit

https://github.com/markdownlang/markdownlang.com
user@example.com
#123
PR #456
a1b2c3d4e5f6

10. Coloration de Lignes dans les Blocs de Code

Mettez en surbrillance des lignes spécifiques dans les blocs de code :

```javascript{2,4}
function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0); // Highlighted
}

const result = calculateSum([1, 2, 3, 4, 5]); // Highlighted
console.log(result);
```

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0); // Highlighted
}

const result = calculateSum([1, 2, 3, 4, 5]); // Highlighted
console.log(result);

11. Coloration Syntaxique Diff

Mettez en surbrillance les modifications de code avec la syntaxe diff :

```diff
- const oldFunction = () => {
-   return "old value";
- };
+
+ const newFunction = () => {
+   return "new value";
+ };
```

- const oldFunction = () => {
-   return "old value";
- };
+
+ const newFunction = () => {
+   return "new value";
+ };

12. Balisage Spécifique à GitHub

Alertes

Utilisez une syntaxe spéciale pour les alertes dans la documentation GitHub :

> [!NOTE]
> Ceci est une alerte de note.

> [!TIP]
> Ceci est une alerte d'astuce.

> [!IMPORTANT]
> Ceci est une alerte importante.

> [!WARNING]
> Ceci est une alerte d'avertissement.

> [!CAUTION]
> Ceci est une alerte de prudence.

NOTE

Ceci est une alerte de note.

TIP

Ceci est une alerte d'astuce.

IMPORTANT

Ceci est une alerte importante.

WARNING

Ceci est une alerte d'avertissement.

CAUTION

Ceci est une alerte de prudence.

Liens Relatifs

Utilisez des liens relatifs pour naviguer entre les fichiers dans le même dépôt :

[README](/fr/README.md)
[Directives de Contribution](/fr/CONTRIBUTING.md)
[Documentation API](/fr/docs/api.md)

Liens d'Image avec Texte au Survol

![GitHub Logo](/fr/images/github-logo.png "GitHub Logo - Texte au Survol")

Utilisation Avancée du GFM

1. Listes Imbriquées avec Listes de Tâches

Combinez des listes imbriquées avec des listes de tâches :

## Feuille de Route du Projet

### Phase 1 : Planification
- [x] Définir la portée du projet
- [x] Identifier les exigences
  - [x] Exigences fonctionnelles
  - [x] Exigences non fonctionnelles
- [x] Créer le calendrier

### Phase 2 : Développement
- [x] Configurer la structure du projet
- [ ] Implémenter les fonctionnalités principales
  - [x] Authentification
  - [ ] Tableau de bord
  - [ ] Intégration API

2. Tableaux avec Emoji et Liens

Améliorez les tableaux avec des emoji et des liens :

| Composant      | Statut              | Mainteneur   |
|----------------|---------------------|--------------|
| Authentification | ✅ Stable          | @johndoe     |
| Base de données | ⚠️ Nécessite mise à jour | @janedoe |
| API            | 🚧 En Cours         | @bobsmith    |
| UI             | ✅ Stable           | @alicesmith  |

Composant	Statut	Mainteneur
Authentification	✅ Stable	@johndoe
Base de données	⚠️ Nécessite mise à jour	@janedoe
API	🚧 En Cours	@bobsmith
UI	✅ Stable	@alicesmith

3. Blocs de Code dans les Listes

Incluez des blocs de code dans les listes :

1. Installer les dépendances :

   ```bash
   npm install

2. Exécuter le serveur de développement :

   npm run dev

3. Construire pour la production :

   npm run build

### 4. Blocs de Citation avec Code

Combinez des citations avec des blocs de code :

```markdown
> **Astuce Pro :** Utilisez la commande suivante pour vérifier rapidement l'état de Git :
>
> ```bash
> git status
> ```

Astuce Pro : Utilisez la commande suivante pour vérifier rapidement l'état de Git :

git status

GFM dans Différents Contextes GitHub

Fichiers README

Les fichiers README prennent en charge toutes les fonctionnalités GFM et sont automatiquement rendus sur les pages du dépôt.

Issues et Pull Requests

• Utilisez des listes de tâches pour suivre les progrès
• Mentionnez les membres de l'équipe pour la collaboration
• Incluez des extraits de code avec coloration syntaxique
• Référencez les issues/PRs connexes en utilisant la syntaxe #123

Commentaires

• Utilisez des emoji pour des réactions rapides
• Référencez des lignes dans le code avec des commentaires de ligne
• Utilisez des blocs de citation pour répondre à des points spécifiques

Wikis

• Organisez le contenu avec des pages imbriquées
• Utilisez des tableaux pour les données structurées
• Incluez des exemples de code avec coloration syntaxique

Bonnes Pratiques

1. Style de Code

<!-- ✅ Bien -->
```javascript
// Utilisez des noms de fonction descriptifs
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

function f(i){return i.reduce((a,b)=>a+b.p,0)}```

2. Conception de Tableau

<!-- ✅ Bien -->
| Fonctionnalité | Description | Statut |
|----------------|-------------|--------|
| Fonctionnalité 1 | Brève description | ✅ |
| Fonctionnalité 2 | Autre description | 🚧 |

<!-- ❌ À Éviter -->
| Fonctionnalité | Description | Statut | | | |
|----------------|-------------|--------|---|---|---|
| Fonctionnalité 1 | Cette description est beaucoup trop longue et rend le tableau difficile à lire sur les appareils mobiles | ✅ | | | |

3. Utilisation des Listes de Tâches

<!-- ✅ Bien -->
## Sprint Backlog
- [x] Terminer la page de profil utilisateur
- [ ] Implémenter la fonctionnalité de recherche
  - [x] API Backend
  - [ ] Composant Frontend
- [ ] Écrire la documentation

<!-- ❌ À Éviter -->
- [ ] Tâche 1
- [ ] Tâche 2
- [ ] Tâche 3
- [ ] Tâche 4
- [ ] Tâche 5
(Trop de tâches sans organisation)

GFM vs Markdown Standard

Fonctionnalité	Markdown Standard	GitHub Flavored Markdown
Blocs de Code Délimités	❌	✅
Coloration Syntaxique	❌	✅
Listes de Tâches	❌	✅
Tableaux	❌	✅
Texte Barré	❌	✅
Emoji	❌	✅
Mentions	❌	✅
Liaison Automatique	Limitée	Étendue

Outils pour Travailler avec GFM

Éditeurs Locaux

• Visual Studio Code - Aperçu GFM et extensions
• Typora - Rendu GFM en temps réel
• Mark Text - Support GFM

Outils en Ligne

• GitHub Gist - Créez et partagez des extraits GFM
• Dillinger - Éditeur GFM en ligne
• StackEdit - Support GFM avec synchronisation cloud

Outils en Ligne de Commande

• glow - Rendu GFM pour terminal
• pandoc - Convertir GFM vers d'autres formats
• marked - Analyseur GFM pour Node.js

Problèmes Courants et Corrections

1. Bloc de Code Non Coloré

Problème : Le bloc de code n'affiche pas la coloration syntaxique

Correction : Assurez-vous de spécifier le bon langage :

<!-- ✅ Correct -->
```javascript
console.log("Hello");

console.log("Hello"); // Utilisation de jsx au lieu de javascript pour du code non-JSX

### 2. Cases à Cocher des Listes de Tâches Non Fonctionnelles

**Problème :** Les cases à cocher des listes de tâches ne sont pas interactives

**Correction :** Assurez-vous d'utiliser la syntaxe correcte (espace entre `-` et `[ ]`) :

```markdown
<!-- ✅ Correct -->
- [ ] Tâche

<!-- ❌ Incorrect -->
-[ ] Tâche (pas d'espace)
-[x] Tâche (pas d'espace)

3. Tableau Non Rendu Correctement

Problème : Les colonnes du tableau sont mal alignées

Correction : Assurez-vous que les barres verticales sont correctement alignées :

<!-- ✅ Correct -->
| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

<!-- ❌ Incorrect -->
|Column 1|Column 2|
|--|--|
|Data 1|Data 2|

Prochaines Étapes

• Apprendre la syntaxe de base de Markdown
• Voir l'antisèche de syntaxe
• S'entraîner avec GitHub Gist
• Lire la documentation officielle GitHub GFM

---

GitHub Flavored Markdown est un outil puissant pour la communication et la collaboration dans le développement logiciel. En maîtrisant ces fonctionnalités, vous pouvez créer une documentation plus efficace, mieux suivre les issues et collaborer plus efficacement avec votre équipe.