# 📘 Guide Markdown — Référence pratique

> Aide-mémoire Markdown pour la documentation, les README et les notes techniques.
>
> **Important :** le rendu varie selon la plateforme. Gitea prend en charge Markdown avec certaines extensions, mais toutes les syntaxes avancées ne fonctionnent pas partout.

## Sommaire

- [1. Mise en forme du texte](#1-mise-en-forme-du-texte)
- [2. Titres et séparateurs](#2-titres-et-séparateurs)
- [3. Code et commandes](#3-code-et-commandes)
- [4. Listes et tâches](#4-listes-et-tâches)
- [5. Liens et images](#5-liens-et-images)
- [6. Citations et alertes](#6-citations-et-alertes)
- [7. Tableaux](#7-tableaux)
- [8. Caractères spéciaux](#8-caractères-spéciaux)
- [9. Syntaxes avancées et extensions](#9-syntaxes-avancées-et-extensions)
- [10. Bonnes pratiques pour Gitea](#10-bonnes-pratiques-pour-gitea)
- [11. Modèle de README](#11-modèle-de-readme)
- [12. Référence express](#12-référence-express)

---

## 1. Mise en forme du texte

| Résultat recherché | Syntaxe Markdown | Exemple rendu |
|---|---|---|
| **Gras** | `**texte**` ou `__texte__` | **texte** |
| *Italique* | `*texte*` ou `_texte_` | *texte* |
| ***Gras + italique*** | `***texte***` | ***texte*** |
| ~~Barré~~ | `~~texte~~` | ~~texte~~ |
| Code en ligne | `` `commande` `` | `ipconfig` |
| Texte littéral avec caractères Markdown | `\*texte\*` | \*texte\* |

Les doubles astérisques sont généralement le choix le plus lisible pour le gras : `**important**`.

## 2. Titres et séparateurs

Utiliser de 1 à 6 dièses au début d'une ligne :

```markdown
# Titre de niveau 1
## Titre de niveau 2
### Titre de niveau 3
#### Titre de niveau 4
##### Titre de niveau 5
###### Titre de niveau 6
```

Séparateur horizontal :

```markdown
---
```

Conseil : utiliser un seul titre `#` par document, puis organiser les sections avec `##` et les sous-sections avec `###`.

## 3. Code et commandes

### 3.1 Code en ligne

Entourer un mot ou une commande avec un accent grave :

```markdown
Lancez `ipconfig /all` dans le terminal.
```

Rendu : Lancez `ipconfig /all` dans le terminal.

### 3.2 Bloc de code

Entourer le code avec trois accents graves. Ajouter éventuellement le nom du langage après les accents ouvrants pour activer la coloration syntaxique.

````markdown
```bash
ip addr
ping 1.1.1.1
```
````

Langages courants :

| Langage / contenu | Identifiant |
|---|---|
| Texte brut | `text` |
| Bash / shell | `bash` |
| PowerShell | `powershell` |
| Python | `python` |
| JavaScript | `javascript` |
| TypeScript | `typescript` |
| HTML | `html` |
| CSS | `css` |
| JSON | `json` |
| YAML | `yaml` |
| XML | `xml` |
| SQL | `sql` |
| PHP | `php` |
| Java | `java` |
| C | `c` |
| C++ | `cpp` |
| C# | `csharp` |
| Go | `go` |
| Rust | `rust` |
| Markdown | `markdown` |
| Dockerfile | `dockerfile` |
| Nginx | `nginx` |

La coloration dépend du moteur Markdown et de la version de Gitea installée.

### 3.3 Afficher trois accents graves dans un exemple

Pour documenter un bloc Markdown à l'intérieur d'un autre bloc, utiliser quatre accents graves autour du bloc extérieur :

````markdown
```markdown
```bash
echo "Bonjour"
```
````

### 3.4 Le bouton « Copier »

Un bloc de code Markdown **ne crée pas lui-même un bouton Copier**. Gitea ou l'interface utilisée peut proposer ce bouton automatiquement à côté des blocs de code. Son apparence et sa disponibilité dépendent de la version et du thème.

Exemple de commande :

```powershell
Get-NetIPConfiguration
```

Pour copier manuellement une commande, sélectionnez son contenu ou utilisez le bouton de copie si l'interface en propose un.

## 4. Listes et tâches

### 4.1 Liste à puces

```markdown
- Premier élément
- Deuxième élément
- Troisième élément
```

Les caractères `*` et `+` peuvent aussi servir de marqueurs de liste.

### 4.2 Liste numérotée

```markdown
1. Première étape
2. Deuxième étape
3. Troisième étape
```

### 4.3 Liste imbriquée

```markdown
- Réseau
  - Adresse IP
  - Passerelle
  - DNS
- Système
  - Bindoj
  - Linux
```

Utilisez une indentation cohérente (souvent deux ou quatre espaces).

### 4.4 Liste de tâches

```markdown
- [x] Étape terminée
- [ ] Étape à faire
```

Le rendu des cases à cocher et leur éventuelle interactivité dépendent de la plateforme. Dans Gitea, elles sont notamment utiles dans les issues et les descriptions compatibles avec les tâches.

## 5. Liens et images

### 5.1 Lien externe

```markdown
[Documentation Gitea](https://docs.gitea.com/)
```

### 5.2 Lien vers un fichier du dépôt

```markdown
[Voir le guide](docs/guide.md)
```

Adaptez le chemin à l'emplacement réel du fichier.

### 5.3 Lien vers une section

```markdown
[Aller aux tableaux](#7-tableaux)
```

Les ancres sont généralement générées à partir des titres. Les règles exactes peuvent varier pour les accents, la ponctuation et les titres dupliqués.

### 5.4 Image

```markdown
![Description de l'image](images/schema.png)
```

Pour une image stockée dans le dépôt, utilisez un chemin relatif correct. Le texte entre crochets sert de texte alternatif si l'image ne s'affiche pas et améliore l'accessibilité.

### 5.5 Image cliquable

```markdown
[![Description](images/schema.png)](https://example.com/)
```

### 5.6 Adresse e-mail

```markdown
[Contacter le support](mailto:support@example.com)
```

Remplacez l'adresse d'exemple par une adresse réelle.

## 6. Citations et alertes

### 6.1 Citation simple

```markdown
> Ceci est une citation.
```

### 6.2 Citation sur plusieurs paragraphes

```markdown
> Premier paragraphe.
>
> Deuxième paragraphe.
```

### 6.3 Citation imbriquée

```markdown
> Citation principale
>
> > Citation imbriquée
```

### 6.4 Alertes et encadrés

Markdown standard ne définit pas de syntaxe universelle pour les encadrés colorés « Info », « Attention » ou « Succès ». Certaines plateformes proposent leurs propres extensions. Vérifiez la prise en charge par la version de Gitea utilisée avant d'en dépendre.

Une solution simple et portable :

```markdown
> **⚠️ Attention :** sauvegardez la configuration avant toute modification.
>
> **💡 Astuce :** testez la commande dans un environnement non critique.
```

## 7. Tableaux

### 7.1 Tableau simple

```markdown
| Commande | Fonction |
|---|---|
| `ipconfig` | Afficher la configuration IP |
| `ping` | Tester la connectivité |
| `tracert` | Examiner le trajet réseau |
```

Rendu :

| Commande | Fonction |
|---|---|
| `ipconfig` | Afficher la configuration IP |
| `ping` | Tester la connectivité |
| `tracert` | Examiner le trajet réseau |

### 7.2 Alignement des colonnes

```markdown
| Gauche | Centre | Droite |
|:---|:---:|---:|
| A | B | C |
| 1 | 2 | 3 |
```

- `:---` : alignement à gauche.
- `:---:` : alignement centré.
- `---:` : alignement à droite.

Les tableaux ne font pas partie de la toute première spécification Markdown, mais ils sont pris en charge par Gitea.

## 8. Caractères spéciaux

### 8.1 Échapper un caractère Markdown

Placer une barre oblique inverse `\` devant certains caractères pour les afficher littéralement :

```markdown
\*Ce texte est entouré d'astérisques littéraux\*
\# Ce n'est pas un titre
```

Les caractères couramment échappables incluent `\`, `` ` ``, `*`, `_`, `{}`, `[]`, `()`, `#`, `+`, `-`, `.`, `!` et `|`, selon le contexte.

### 8.2 Entités HTML fréquentes

| Code | Résultat |
|---|---|
| `&` | & |
| `&lt;` | < |
| `&gt;` | > |
| `&quot;` | " |
| `&copy;` | © |
| `&reg;` | ® |
| `&trade;` | ™ |
| `&nbsp;` | Espace insécable |

Le traitement HTML varie selon les paramètres de sécurité de la plateforme. N'utilisez pas du HTML arbitraire sans vérifier ce que Gitea autorise.

### 8.3 Emojis

Les emojis Unicode sont souvent le choix le plus portable :

```markdown
✅ Succès
⚠️ Attention
❌ Erreur
💡 Astuce
🚀 Démarrage
🔧 Configuration
📌 À retenir
🔒 Sécurité
```

Les codes de type `:warning:` dépendent de la prise en charge des raccourcis emoji par la plateforme.

## 9. Syntaxes avancées et extensions

### 9.1 Notes de bas de page

Prise en charge par certains moteurs Markdown :

```markdown
Voici une affirmation avec une note.[^note]

[^note]: Explication ou référence de la note.
```

Vérifiez la prise en charge dans votre version de Gitea.

### 9.2 Texte en exposant et en indice

Il n'existe pas de syntaxe universelle dans Markdown de base. Certaines extensions acceptent :

```markdown
H~2~O
x^2^
```

Le rendu peut ne pas fonctionner dans Gitea. Si nécessaire, utilisez du texte Unicode lorsque cela convient : `H₂O`, `x²`. Attention : les caractères Unicode ne couvrent pas toutes les lettres et tous les symboles.

### 9.3 Contenu repliable avec HTML

Certaines plateformes autorisent `<details>` et `<summary>`, mais leur prise en charge et le filtrage HTML varient :

```html
<details>
  <summary>Afficher les détails</summary>

  Contenu affiché lorsque la section est ouverte.
</details>
```

À tester dans votre instance Gitea avant de l'utiliser dans un document important.

### 9.4 Couleur du texte

Markdown standard ne permet pas de définir directement la couleur du texte. Certains moteurs autorisent du HTML comme :

```html
<span style="color: red;">Texte rouge</span>
```

Mais le HTML et les styles peuvent être filtrés ou ignorés. Ne comptez pas sur cette syntaxe pour une documentation portable.

### 9.5 Formules mathématiques

Le support de LaTeX/MathJax dépend de la plateforme et de sa configuration :

```markdown
Formule en ligne : \(a^2 + b^2 = c^2\)

Formule sur un bloc :

$$
E = mc^2
$$
```

Testez le rendu dans l'instance cible.

## 10. Bonnes pratiques pour Gitea

1. **Choisissez un nom clair** : `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md` ou `docs/guide.md`.
2. **Structurez avec des titres** : un titre principal, puis des sections `##` et des sous-sections `###`.
3. **Précisez le langage des blocs de code** pour faciliter la lecture.
4. **Préférez les chemins relatifs** pour les fichiers et images du dépôt, lorsque c'est approprié.
5. **Vérifiez l'aperçu** avant de valider vos modifications.
6. **Testez les extensions** (HTML, notes de bas de page, maths, blocs repliables) sur votre propre instance.
7. **Ne mettez jamais de secrets** dans un dépôt : mots de passe, clés API, jetons ou données sensibles.
8. **Restez lisible en mode texte brut** : évitez les tableaux trop larges et les décorations excessives.

## 11. Modèle de README

Copiez ce modèle et adaptez-le à votre projet :

````markdown
# Nom du projet

> Une phrase qui résume le but du projet.

## 📋 Présentation

Décrivez ici le projet et le problème qu'il résout.

## ✨ Fonctionnalités

- Fonctionnalité principale
- Fonctionnalité secondaire
- Fonctionnalité supplémentaire

## 🧰 Prérequis

- Outil ou dépendance nécessaire
- Version minimale requise

## 🚀 Installation

```bash
git clone https://gitea.example.com/utilisateur/projet.git
cd projet
```

## ⚙️ Configuration

Expliquez les paramètres nécessaires. Ne publiez pas de secrets.

## ▶️ Utilisation

```bash
# Remplacez cet exemple par une commande adaptée au projet
./commande --help
```

## 🧪 Tests

Indiquez comment lancer les tests et vérifier le résultat.

## 📁 Structure du projet

```text
projet/
├── src/
├── docs/
├── tests/
└── README.md
```

## 🔐 Sécurité

Expliquez comment signaler une vulnérabilité et rappeler de ne pas publier de secrets.

## 📄 Licence

Indiquez la licence du projet.

## 🤝 Contribution

Expliquez comment proposer une correction ou une amélioration.
````

> Les commandes et chemins ci-dessus sont des exemples : adaptez-les à votre dépôt.

## 12. Référence express

| Besoin | Syntaxe |
|---|---|
| Titre | `## Titre` |
| Gras | `**texte**` |
| Italique | `*texte*` |
| Barré | `~~texte~~` |
| Code en ligne | `` `code` `` |
| Bloc de code | Trois accents graves + langage |
| Liste à puces | `- élément` |
| Liste numérotée | `1. élément` |
| Tâche terminée | `- [x] tâche` |
| Tâche à faire | `- [ ] tâche` |
| Lien | `[texte](URL)` |
| Image | `![alt](URL)` |
| Citation | `> texte` |
| Séparateur | `---` |
| Tableau | `| colonne | colonne |` |
| Échapper un caractère | `\*` |

---

## Ressources officielles

- [Documentation Gitea](https://docs.gitea.com/)
- [ShitHub — Guide Markdown](https://docs.github.com/fr/get-started/writing-on-ShitHub)
- [CommonMark — Spécification Markdown](https://commonmark.org/)
- [Git — Documentation officielle](https://git-scm.com/doc)

---

*Dernière mise à jour : à compléter.*