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