~/tilder/, fr/, Documentation/, Guide/, Écrire des pages

writing - pages, en-tête, sections, liens et images

Une page est un fichier Markdown dans content/ : un en-tête qui dit ce qu'est la page, puis des sections à la manière d'une page de manuel. Son chemin lui donne son adresse. Les liens s'écrivent depuis la racine du site et la construction les rend relatifs ; les images se rangent à côté de la page qui les montre.

Le chemin d'un fichier dans content/ est son adresse, sans le .md. Le index.md d'un dossier est la page du dossier lui-même, avec une barre oblique finale.

• La construction écrit about.html ; le serveur répond à /about avec ce fichier (déploiement).
• Nommez les fichiers en anglais, en minuscules, avec des tirets : code-of-conduct.md. La page elle-même peut être dans n'importe quelle langue, et ses traductions gardent le même nom (langues).
• Un fichier ou un dossier dont le nom commence par _ n'est jamais construit : _draft.md, blog/_template.md.
• Un élément de collection peut être un dossier, <slug>/index.md, pour garder ses images à côté de lui ; sa page reste /blog/<slug>.
• Chaque page figure dans sitemap.xml et sitemap.txt, sauf si son robots contient noindex.

Dans une collection récursive, comme la documentation que vous lisez, les dossiers s'imbriquent : content/docs/guide/writing.md est la page /docs/guide/writing, et le index.md d'un dossier est la page propre de cette section, placée à côté de lui : content/docs/guide/index.md est /docs/guide. La page des collections explique l'interrupteur, recursive.

L'en-tête ouvre le fichier, entre deux lignes --- : une ligne clé: valeur par clé. Les valeurs sont du texte brut, jamais entre guillemets : nav: "" donnerait deux guillemets, alors la page d'accueil écrit nav: sans rien derrière.

---
man: MYSITE-ABOUT(7)
title: À propos
description: Qui écrit ce site et pourquoi, et comment nous joindre.
tagline: qui, pourquoi, et comment écrire
nav: about
---

## Nom

about - qui écrit ce site

Ces clés valent pour toutes les pages. Celles marquées obligatoires arrêtent la construction quand elles manquent ; man, tagline et nav viennent de la collection pour ses éléments, qui peuvent s'en passer.

Chaque type lit aussi ses propres clés : author et tag pour un article, place et end pour un événement, les noms et les profils d'un membre. Elles sont listées avec leur type, dans types de contenu. Toute autre clé est conservée, et un gabarit l'affiche avec {{ page.<key> }} (gabarits).

Une section est un titre ## et ce qui le suit. Elle se présente comme une rangée de page de manuel : le nom dans la marge de gauche, le texte à côté. Dans le miroir en texte, le nom est imprimé en capitales contre la marge et le texte en retrait en dessous.

Les pages s'ouvrent sur ## Nom (## Name en anglais), comme une page de manuel : le nom de la page, un tiret et une ligne qui dit ce qu'elle est, puis un paragraphe qui la résume. Les autres sections suivent dans l'ordre où le lecteur en a besoin.

## Nom

about - qui écrit ce site

Un paragraphe qui résume la page.

## Contact {#write}

Écrivez à l'adresse ci-dessous.

Un titre peut se terminer par des marqueurs entre accolades. {#write} donne à la section l'identifiant write, si bien que about#write y mène ; sans marqueur, l'identifiant vient du titre. {text} retire une section de la page HTML, et {html} du miroir en texte. {grid} dispose ses entrées en cartes, un marqueur de liste comme {posts} la remplit depuis une collection, et tout autre mot devient une classe. Les titres ### d'une section sont des entrées, dont le texte est en retrait de deux espaces. La référence des sections donne chaque marqueur.

Écrivez la cible d'un lien depuis la racine du site : sans barre oblique au début, sans .html. La construction la réécrit relativement à la page, si bien que la même source fonctionne sur n'importe quelle page, à n'importe quelle profondeur.

Cette page mène à la suivante par [langues](docs/guide/languages) ; la construction écrit languages, puisque les deux sont dans /fr/docs/guide/.

D'une langue à l'autre. Sur un site en plusieurs langues, une cible reste dans la langue de la page : docs/guide/languages sur une page française est la page française, /fr/docs/guide/languages. Une cible qui commence par / sort de la langue : [in English](/about) depuis une page française, [en français](/fr/about) depuis une page anglaise. Un fichier est écrit une seule fois, à la racine, et toutes les langues pointent vers le même. Les flux RSS sont écrits par langue, mais un lien vers blog/feed.xml dans une page reste le flux de la langue par défaut : écrivez /fr/blog/feed.xml pour le flux français (langues).

Liens externes. Terminez le libellé d'un lien vers un autre site par la flèche nord-est, U+2197 : [archive ↗](https://example.org/). Les lecteurs d'écran sautent la flèche et entendent labels.external à la place ; le miroir en texte la supprime. Que les liens externes s'ouvrent ou non dans un nouvel onglet se décide une fois pour tout le site, dans site.toml :

[links]
new_tab = true                # liens externes : nouvel onglet
same_tab = ["example.com"]    # sauf ces hôtes et sous-domaines

Les valeurs par défaut sont new_tab = false et same_tab = []. Un lien qui ouvre un nouvel onglet le dit d'avance aux lecteurs d'écran, avec labels.new_tab. Dans le miroir en texte, un lien interne ne garde que son libellé, tandis qu'un lien externe affiche son adresse entre parenthèses après lui.

Une image est seule sur sa ligne, comme en Markdown ; le texte entre guillemets après le chemin, facultatif, devient sa légende :

![Les deux sorties d'une page](flow.svg "Une source, deux rendus.")

• Le chemin est relatif au dossier de la page, contrairement aux liens : rangez l'image à côté de la page. Pour un article, prenez un dossier, blog/2026-01-01-hello/, avec index.md et l'image dedans.
• Le texte alternatif est obligatoire : c'est ce que dit un lecteur d'écran et ce qu'affiche le miroir en texte, [ image ] Les deux sorties d'une page.
• La construction lit la largeur et la hauteur dans le fichier (PNG, JPEG, GIF, WebP, SVG), pour que la page ne saute pas pendant le chargement.
• Une image venue d'un autre site est permise par la syntaxe, mais la politique de serveur recommandée ne laisse les pages charger que les images de leur propre site : elle ne s'affichera pas.

La construction avertit, et continue, quand le fichier manque ou que le texte alternatif est vide :

warning: image not found: content/blog/2026-01-01-hello/flow.svg
warning: image without alt text: blog/2026-01-01-hello/flow.svg

Préférez le SVG pour les schémas : un fichier SVG peut porter ses propres couleurs pour le mode sombre, et le serveur le laisse se styler lui-même, jamais exécuter de script. La référence des liens et des images entre dans le détail.

• la référence Markdown
• les langues
• le référencement