From 4a39a1baf6093b4e1361e4c2c23d6256dabdcbbb Mon Sep 17 00:00:00 2001 From: Jojo - InfoMaker Date: Fri, 23 Oct 2026 19:01:53 +0200 Subject: [PATCH] Add Guide-Markdown.md --- Guide-Markdown.md | 517 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 517 insertions(+) create mode 100644 Guide-Markdown.md diff --git a/Guide-Markdown.md b/Guide-Markdown.md new file mode 100644 index 0000000..aa280a8 --- /dev/null +++ b/Guide-Markdown.md @@ -0,0 +1,517 @@ +# 📘 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 | +|---|---| +| `&` | & | +| `<` | < | +| `>` | > | +| `"` | " | +| `©` | © | +| `®` | ® | +| `™` | ™ | +| ` ` | 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 `
` et ``, mais leur prise en charge et le filtrage HTML varient : + +```html +
+ Afficher les détails + + Contenu affiché lorsque la section est ouverte. +
+``` + +À 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 +Texte rouge +``` + +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.*