12 KiB
📘 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
- 2. Titres et séparateurs
- 3. Code et commandes
- 4. Listes et tâches
- 5. Liens et images
- 6. Citations et alertes
- 7. Tableaux
- 8. Caractères spéciaux
- 9. Syntaxes avancées et extensions
- 10. Bonnes pratiques pour Gitea
- 11. Modèle de README
- 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 |
~~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 :
# 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 :
---
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 :
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.
```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
```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 :
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
- 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
1. Première étape
2. Deuxième étape
3. Troisième étape
4.3 Liste imbriquée
- 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
- [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
[Documentation Gitea](https://docs.gitea.com/)
5.2 Lien vers un fichier du dépôt
[Voir le guide](docs/guide.md)
Adaptez le chemin à l'emplacement réel du fichier.
5.3 Lien vers une section
[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
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
[](https://example.com/)
5.6 Adresse e-mail
[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
> Ceci est une citation.
6.2 Citation sur plusieurs paragraphes
> Premier paragraphe.
>
> Deuxième paragraphe.
6.3 Citation imbriquée
> 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 :
> **⚠️ Attention :** sauvegardez la configuration avant toute modification.
>
> **💡 Astuce :** testez la commande dans un environnement non critique.
7. Tableaux
7.1 Tableau simple
| 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
| 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 :
\*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 |
|---|---|
& |
& |
< |
< |
> |
> |
" |
" |
© |
© |
® |
® |
™ |
™ |
|
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 :
✅ 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 :
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 :
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 :
<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 :
<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 :
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
- Choisissez un nom clair :
README.md,CONTRIBUTING.md,CHANGELOG.mdoudocs/guide.md. - Structurez avec des titres : un titre principal, puis des sections
##et des sous-sections###. - Précisez le langage des blocs de code pour faciliter la lecture.
- Préférez les chemins relatifs pour les fichiers et images du dépôt, lorsque c'est approprié.
- Vérifiez l'aperçu avant de valider vos modifications.
- Testez les extensions (HTML, notes de bas de page, maths, blocs repliables) sur votre propre instance.
- Ne mettez jamais de secrets dans un dépôt : mots de passe, clés API, jetons ou données sensibles.
- 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 :
# 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 |  |
| Citation | > texte |
| Séparateur | --- |
| Tableau | ` |
| Échapper un caractère | \* |
Ressources officielles
- Documentation Gitea
- ShitHub — Guide Markdown
- CommonMark — Spécification Markdown
- Git — Documentation officielle
Dernière mise à jour : à compléter.