JojoInfoMaker/Guide-Markdown-Pratique
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Folder "Chapitres" and files all chapters

Browse Source
This commit is contained in:
Jojo - InfoMaker committed 2026-10-23 19:10:45 +02:00
1 parent 4a39a1baf6
commit 1a2d3059b3
13 files changed
+495 -507
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

Guide-Markdown.md
+12 -507
View File
@@ -6,512 +6,17 @@
## 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](Chapitres/1.%20Mise%20en%20forme%20du%20texte.md)
2. [Titres et séparateurs](Chapitres/2.%20Titres%20et%20s%C3%A9parateurs.md)
3. [Code et commandes](Chapitres/3.%20Code%20et%20commandes.md)
4. [Listes et tâches](Chapitres/4.%20Listes%20et%20t%C3%A2ches.md)
5. [Liens et images](Chapitres/5.%20Liens%20et%20images.md)
6. [Citations et alertes](Chapitres/6.%20Citations%20et%20alertes.md)
7. [Tableaux](Chapitres/7.%20Tableaux.md)
8. [Caractères spéciaux](Chapitres/8.%20Caract%C3%A8res%20sp%C3%A9ciaux.md)
9. [Syntaxes avancées et extensions](Chapitres/9.%20Syntaxes%20avanc%C3%A9es%20et%20extensions.md)
10. [Bonnes pratiques pour Gitea](Chapitres/10.%20Bonnes%20pratiques%20pour%20Gitea.md)
11. [Modèle de README](Chapitres/11.%20Mod%C3%A8le%20de%20README.md)
12. [Référence express](Chapitres/12.%20R%C3%A9f%C3%A9rence%20express.md)
---
## 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.*