É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.

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.

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 :

---
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¶

# 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 :

## 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¶

- 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 :

- [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.

Liens¶

[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¶

![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 :

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

Citations¶

> 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 :

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

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 :

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

cd /etc/apache2
sudo nano apache2.conf
sudo systemctl reload apache2

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.

!!! 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.

Bon à savoir

Le contenu est indenté de quatre espaces.

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 :

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

Pourquoi cette commande fonctionne

L'explication détaillée, que le lecteur ouvre s'il le souhaite.

Tableaux¶

| 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¶

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

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

Le noyau Linux est publié sous licence GPLv2¹.

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 :

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

Télécharger Linux Mint

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 :

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

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. 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
Référence Markdown complète
Documentation du thème Material — toutes les possibilités du thème ; certaines demandent d'activer une extension dans mkdocs.yml, à discuter avec les mainteneurs.

GNU General Public License, version 2. ↩