alpinux-wiki/docs/contribuer/markdown.md

---
description: Toute la syntaxe utilisable dans le wiki Alpinux — titres, listes, liens, images, code, alertes, tableaux, blocs dépliables, notes de bas de page.
---

# Écrire en Markdown

Le **Markdown** est un langage de mise en forme qui s'écrit en texte brut : on indique la
structure avec quelques caractères, et le site s'occupe de l'apparence. Pas de police à
choisir, pas de taille de titre à régler — vous écrivez le fond, le thème fait la forme.

Cette page recense ce qui fonctionne **sur ce wiki**. Certaines syntaxes présentées
ailleurs sur Internet n'y sont pas activées : si un élément ne s'affiche pas comme prévu,
vérifiez d'abord qu'il figure ici.

!!! tip "Voir avant de publier"
    L'éditeur de la forge a un onglet **Aperçu**. En local, `mkdocs serve` affiche le
    rendu réel, thème compris — voir
    [Rédiger en ligne de commande](ligne-de-commande.md).

---

## L'en-tête de la page

Chaque page commence idéalement par un bloc encadré de `---`, qui n'apparaît pas à
l'écran mais alimente les moteurs de recherche et les liens partagés :

```yaml
---
description: Une phrase qui résume la page, affichée dans les résultats de recherche.
---
```

Puis vient le titre principal, et lui seul : le `#` de niveau 1 ne s'emploie **qu'une
fois par page**.

---

## Titres

```markdown
# Titre principal (H1) — un seul par page
## Section (H2)
### Sous-section (H3)
#### Détail (H4)
```

Les titres construisent le sommaire affiché à droite de chaque page. Pas de saut de
niveau : après un `##`, on met un `###`, pas un `####`.

Pour fixer soi-même l'ancre d'un titre — utile quand on veut un lien stable malgré une
reformulation future :

```markdown
## Un titre un peu long {#ancre-courte}
```

---

## Mise en forme du texte

| Ce que vous écrivez | Résultat |
|---|---|
| `**important**` | **important** |
| `*nuance*` | *nuance* |
| `` `code` `` | `code` |

Le barré (`~~texte~~`) et le surligné (`==texte==`) ne sont pas activés sur ce wiki : ils
s'afficheraient tels quels, avec leurs tildes ou leurs signes égal.

Pour aller à la ligne sans changer de paragraphe, terminez la ligne par deux espaces.
Une ligne vide crée un nouveau paragraphe.

---

## Listes

```markdown
- Premier élément
- Deuxième élément
    - Sous-élément (quatre espaces d'indentation)

1. Première étape
2. Deuxième étape
```

L'indentation d'une sous-liste est de **quatre espaces**. Avec deux, la liste est
ignorée : c'est l'erreur la plus fréquente.

### Listes de tâches

Pour une checklist, une paire de crochets suffit — cochée avec un `x` :

```markdown
- [x] Étape faite
- [ ] Étape à faire
```

Les cases sont décoratives : le lecteur ne peut pas les cocher dans son navigateur. Elles
servent aux procédures qu'on suit une fois, comme la
[préparation d'un serveur Debian](../technique/serveur-debian-13.md).

---

## Liens

```markdown
[Texte du lien](https://example.org)
[Lien vers une autre page du wiki](../guides/linux-mint-depuis-windows.md)
[Lien vers une section précise](../guides/docker.md#installer-docker-engine)
```

Pour les pages du wiki, **liez le fichier `.md`, pas l'adresse du site** : MkDocs
transforme le chemin en URL et vous prévient si la page n'existe pas. Un lien écrit en
dur vers `https://wiki.alpinux.org/…` continuera de pointer dans le vide après un
renommage, sans que personne ne s'en aperçoive.

Les chemins sont relatifs à la page courante : `../guides/…` depuis une page de
`contribuer/`, `docker.md` depuis une autre page de `guides/`.

---

## Images

```markdown
![Texte alternatif décrivant l'image](https://static.alpinux.org/wiki/exemple.png)
```

Les images ne sont pas stockées dans le dépôt : elles sont hébergées sur
**static.alpinux.org** et appelées par leur adresse complète. Pour ajouter une image à un
article, demandez à un bénévole de la déposer.

Le texte alternatif n'est pas décoratif : il est lu par les lecteurs d'écran et s'affiche
si l'image ne charge pas. Décrivez ce qu'on y voit, pas « capture d'écran ».

Pour une largeur maîtrisée :

```markdown
![Logo Alpinux](https://static.alpinux.org/logo/alpinux-logo.png){ width="200" }
```

---

## Citations

```markdown
> Le logiciel libre, c'est une question de liberté, pas de prix.
```

> Le logiciel libre, c'est une question de liberté, pas de prix.

---

## Blocs de code

Encadrez par trois accents graves, en précisant le langage — c'est lui qui déclenche la
coloration :

````markdown
```bash
sudo apt update
sudo apt install mon-paquet
```
````

```bash
sudo apt update
sudo apt install mon-paquet
```

Langages courants : `bash`, `python`, `yaml`, `json`, `html`, `css`, `sql`, `ini`. Sans
langage, le bloc reste lisible mais sans couleurs — utile pour un affichage de terminal
ou un arbre de fichiers.

Pour attirer l'œil sur une ligne précise :

````markdown
```bash hl_lines="2"
cd /etc/apache2
sudo nano apache2.conf
sudo systemctl reload apache2
```
````

```bash hl_lines="2"
cd /etc/apache2
sudo nano apache2.conf
sudo systemctl reload apache2
```

!!! warning "Commandes à recopier"
    Dans un bloc destiné à être recopié, ne mettez pas le `$` du prompt : le lecteur qui
    copie la ligne collerait un `$` qui fait échouer la commande.

---

## Alertes

Les alertes (*admonitions*) mettent en valeur une remarque. Syntaxe : `!!!`, le type, et
un titre entre guillemets — facultatif.

```markdown
!!! note "Bon à savoir"
    Le contenu est indenté de quatre espaces.

!!! tip "Astuce"
    Un raccourci qui fait gagner du temps.

!!! warning "Attention"
    Un piège fréquent, une manipulation à ne pas rater.

!!! danger "Danger"
    Une action destructrice : effacer un disque, supprimer des données.

!!! success "C'est bon"
    Confirmation que tout s'est bien passé.

!!! info "Information"
    Un complément, une précision de contexte.
```

!!! note "Bon à savoir"
    Le contenu est indenté de quatre espaces.

!!! warning "Attention"
    Un piège fréquent, une manipulation à ne pas rater.

### Blocs dépliables

En remplaçant `!!!` par `???`, le bloc est replié ; avec `???+`, il est déplié au
chargement. Pratique pour une explication longue qui ne doit pas couper la lecture :

```markdown
??? info "Pourquoi cette commande fonctionne"
    L'explication détaillée, que le lecteur ouvre s'il le souhaite.
```

??? info "Pourquoi cette commande fonctionne"
    L'explication détaillée, que le lecteur ouvre s'il le souhaite.

---

## Tableaux

```markdown
| Colonne 1 | Colonne 2 |
|---|---|
| Valeur A | Valeur B |
```

Les tirets de la deuxième ligne séparent l'en-tête du corps ; leur nombre n'a pas
d'importance. Pour aligner une colonne, placez un `:` du côté voulu : `|---:|` à droite,
`|:---:|` au centre.

Un tableau large devient illisible sur téléphone : au-delà de quatre ou cinq colonnes,
préférez une liste.

---

## Notes de bas de page

```markdown
Le noyau Linux est publié sous licence GPLv2[^1].

[^1]: GNU General Public License, version 2.
```

Le noyau Linux est publié sous licence GPLv2[^1].

[^1]: GNU General Public License, version 2.

La note s'affiche en bas de page, quel que soit l'endroit où vous l'écrivez.

---

## Boutons

Avec un attribut `{ .md-button }`, un lien devient un bouton :

```markdown
[Télécharger Linux Mint](https://linuxmint.com/download.php){ .md-button }
```

[Télécharger Linux Mint](https://linuxmint.com/download.php){ .md-button }

---

## Conseils de rédaction

Au-delà de la syntaxe, ce qui rend une page utile :

- **Une page, un sujet.** Si le titre contient « et », il y a peut-être deux pages.
- **Écrivez pour qui ne sait pas.** Ce qui vous paraît évident est précisément ce que le
  lecteur cherche. Indiquez où cliquer, ce qui doit s'afficher, comment vérifier que
  l'étape a réussi.
- **Datez ce qui vieillit.** Une version de logiciel, une capture d'écran, une adresse :
  précisez à quelle date c'était vrai.
- **Préférez la phrase courte.** Un guide se lit un ordinateur en panne sur les genoux.

---

## Diagrammes

Un schéma se décrit en texte, dans un bloc `mermaid` — le thème le dessine à l'affichage :

````markdown
```mermaid
flowchart LR
  A[Rédiger] --> B[Pull request]
  B --> C[Relecture]
  C --> D[En ligne]
```
````

```mermaid
flowchart LR
  A[Rédiger] --> B[Pull request]
  B --> C[Relecture]
  C --> D[En ligne]
```

La syntaxe complète est documentée sur [mermaid.js.org](https://mermaid.js.org/). Un
schéma reste plus long à maintenir qu'une liste : réservez-le à ce qu'une phrase explique
mal, comme un enchaînement d'étapes ou une architecture.

---

## Pour aller plus loin

- [Éditeur Markdown en ligne, avec aperçu](https://markdownlivepreview.com/)
- [Référence Markdown complète](https://www.markdownguide.org/basic-syntax/)
- [Documentation du thème Material](https://squidfunk.github.io/mkdocs-material/reference/) —
  toutes les possibilités du thème ; certaines demandent d'activer une extension dans
  `mkdocs.yml`, à discuter avec les mainteneurs.