Stratégie d’URL

L’URL canonique devrait généralement venir du chemin du contenu. L’emplacement du fichier Markdown et son nom sont la source de vérité, sauf lorsqu’une page a un vrai besoin de routage que le système de fichiers n’exprime pas proprement.

URL stables#

Une URL n’est pas qu’une adresse; elle fait partie du dossier public d’une page. Quand quelqu’un crée un lien vers une page, la garde dans ses notes, la cite dans un document ou l’envoie dans un message, l’adresse devient une partie de l’utilité du travail. Si l’adresse casse, le contenu existe peut-être encore, mais le lien est rompu.

Chaque information a un seul foyer canonique : l’URL où elle est maintenue dans le temps. D’autres pages peuvent la résumer, d’autres plateformes peuvent la rediffuser et des raccourcis peuvent pointer vers elle, mais une seule URL reste l’endroit à privilégier pour lier, réviser et préserver le travail.

• gardez les chemins publics prévisibles
• utilisez des redirections quand une page déménage
• évitez les slugs propres à une plateforme quand un chemin local plus simple suffit
• préservez les anciennes URL quand des liens externes peuvent déjà exister
• traitez les alias comme de l’entretien, pas comme du désordre

Conventions de chemins#

Les visiteurs arrivent rarement par la page d’accueil. Ils passent par des liens, des résultats de recherche, des signets et de vieilles références; un emplacement conventionnel est un emplacement que personne n’a besoin d’expliquer. Certains chemins sont porteurs parce que tout le monde s’y attend: /about, /blog, /contact et /privacy.

Les noms de dossiers séparent les collections des ressources individuelles:

• Pluriel pour les collections : les pages d’index et de navigation utilisent des noms au pluriel parce qu’elles représentent un ensemble d’items, comme /talks/, /projects/ et /tags/
• Singulier pour les pages uniques : les pages qui représentent un seul concept ou une fonction administrative utilisent le singulier, comme /about/, /search/ et /contact/
• L’exception du blogue : les articles individuels vivent sous le slug historique /blog pour garder les essais clairement séparés de la documentation et des références de données

Fichiers racine et /.well-known/#

Les outils ne devinent pas; ils s’attendent à des fichiers précis à des emplacements précis. Les fichiers établis de longue date restent à la racine du site, pas sous /.well-known/:

• /favicon.ico pour les onglets de navigateur, les signets et les résultats de recherche
• /index.xml ou /feed.xml pour la syndication standard
• /robots.txt pour les règles d’accès des robots, normalisé dans la RFC 9309 (2022) après 25 ans comme convention de fait
• /sitemap.xml pour la visibilité dans les moteurs de recherche, selon le protocole sitemaps.org

Les métadonnées de site plus récentes vont sous /.well-known/, l’espace de noms que la RFC 8615 réserve pour qu’un outil trouve les métadonnées d’un site sans gratter les pages ni deviner. Le registre Well-Known URIs de l’IANA liste les suffixes enregistrés.

Les surfaces publiées par ce site sont documentées dans Surfaces lisibles par machine.

Front matter par défaut#

Le front matter devrait décrire des différences utiles, pas répéter les valeurs par défaut de Hugo.

N’ajoutez pas ces valeurs lorsqu’elles sont vides ou fausses par défaut:

• sitemap_exclude: false
• description: ""
• tags: []
• aliases: vide
• draft: false

Utilisez ces champs seulement lorsqu’ils changent le comportement:

• sitemap_exclude: true pour les pages qui doivent être rendues mais rester hors du sitemap HTML et du sitemap XML;
• pagefind_exclude: true pour les pages qui doivent être rendues mais rester hors de la recherche;
• draft: true pour les pages qui doivent rester hors des builds de production normaux;
• layout: lorsqu’une page utilise une mise en page spéciale, pilotée par les données ou sur mesure;
• type: lorsque la résolution de gabarit ou le regroupement Hugo a besoin d’un type de section différent de la section physique;
• collection: lorsque la page appartient à une vraie collection du site, comme les références, les slash pages ou une série de blogue.

Il n’y a pas d’exception de page de contenu pour draft: false. Utilisez-le seulement dans des exemples ou de la documentation qui montrent explicitement les états de front matter Hugo.

Front matter url#

N’ajoutez pas url: lorsque la valeur répète seulement l’URL que Hugo produit déjà à partir du dossier de contenu monté, du suffixe de langue, de la section, du nom de fichier ou du dossier _index.

Utilisez un url: explicite seulement pour de vraies exceptions:

• les fichiers racine lisibles par machine comme /security.txt, /.well-known/security.txt, /humans.txt, /human.txt, /llms.txt et /llms-full.txt, sauf si un format de sortie ou une règle de routage dédiée possède ce chemin;
• les pages de redirection ou de compatibilité dont l’emplacement de fichier n’est volontairement pas le chemin public;
• les pages utilitaires imbriquées dont le chemin public propre ne peut pas être représenté sans dégrader le modèle de contenu, comme les pages de confirmation sous /contact/;
• les pages qui doivent vivre à une URL imbriquée qui ne peut pas être représentée en déplaçant le fichier sans dégrader la structure du contenu.

Exceptions url: intentionnelles actuelles:

• human*.en.md, humans*.en.md, llms*.en.md et security*.en.md publient les fichiers racine lisibles par machine sur chaque site.
• content/legal/privacy-redirect.*.md conserve l’ancien chemin racine de confidentialité et redirige vers l’avis de confidentialité légal.
• content/blog/ref/phonetic-alphabet-world.*.md reste physiquement près du contenu de référence phonétique connexe, mais publie comme article de blogue régulier.

Front matter slug#

Utilisez slug: lorsque la page a besoin d’un segment final d’URL localisé ou plus propre tout en conservant la structure de contenu partagée entre les langues.

C’est courant pour les pages françaises: le fichier peut rester apparié au fichier anglais, tandis que le segment visible de l’URL utilise le terme français.

Lorsqu’une page française utilise un slug: localisé, gardez la route équivalente de style anglais comme alias si quelqu’un pourrait raisonnablement l’essayer.

Front matter aliases#

Utilisez les alias pour les routes alternatives qui doivent continuer à résoudre. Ils sont utiles lorsqu’une page est renommée, déplacée ou susceptible d’être demandée par un chemin court populaire. Quand la structure change, l’ancien chemin ne casse pas; il devient une redirection permanente vers le nouveau. Passez régulièrement en revue les rapports 404 pour repérer les routes qui auraient dû être préservées.

Rien de tout cela n’est gratuit. Chaque URL qu’on promet de garder vivante est de l’entretien assumé pour toujours, et une table de redirections ne fait que grossir. Chaque lien ne mérite pas un engagement de quarante ans, mais un site personnel devrait survivre à trois migrations de plateforme.

Sur un site bilingue, certaines pages méritent un alias au niveau racine parce que des gens peuvent demander le chemin qui existerait sur un site monolingue. L’alias est une route de commodité; la page canonique devrait tout de même vivre sous l’URL préfixée par la langue.

Les alias au niveau racine appartiennent seulement à la page anglaise. La page anglaise peut aussi garder des variantes préfixées par /en/... pour les redirections explicites. La page française devrait utiliser des alias en /fr/...; lorsqu’elle utilise un slug: localisé, elle devrait garder un alias pour le nom de fichier anglais dans la même section.

Exceptions d’alias intentionnelles actuelles:

• Les pages de mindmaps gardent les anciens alias en camelCase comme /blog/macOSHistory/, /blog/mindmaps/macOSHistory/ et /blog/publications/macOSHistory/ comme routes de compatibilité. Gardez la page anglaise comme propriétaire des alias racine et ne conservez que les variantes préfixées par /en/... et /fr/... sur les pages de langue correspondantes.

URL de blogue#

N’ajoutez pas de url: inutile aux pages de blogue. Les pages de blogue devraient suivre le chemin du contenu par défaut, donc une page sous content/blog/ref/airline-codes.en.md possède naturellement /en/blog/ref/airline-codes/.

Si une URL de blogue doit différer du chemin de fichier, demandez-vous d’abord si le fichier devrait être déplacé ou si slug: suffit. Utilisez url: seulement lorsqu’aucune de ces options n’exprime proprement la route.

Emplacement physique#

Placez le fichier Markdown à l’endroit où l’URL canonique devrait vivre. Le dossier donne le contexte, la responsabilité et le préfixe d’URL; le nom de fichier donne le segment final.

Les index de référence peuvent tout de même pointer vers du contenu qui vit ailleurs. Par exemple, la référence des spécifications techniques de macOS vit sous content/blog/macos/_index.*.md, tandis que les archives des versions vivent à côté sous content/blog/macos/. Le fichier de données stocke ces liens d’archive canoniques au lieu de forcer une deuxième couche de routage.

Utilisez ce modèle lorsqu’une page pilotée par les données sert d’index sur du contenu lié, mais que les pages indexées appartiennent à une URL de sujet ou de série plus propre.

Noms de fichiers dans une série#

Dans un dossier de série ou de sujet, ne répétez pas le nom de la série dans chaque nom de fichier. Le dossier possède déjà cette partie de l’URL et du contexte.

Préférez content/blog/files/naming-convention.en.md à content/blog/files/file-naming-convention.en.md, et content/blog/naming/naming-convention.en.md à content/blog/naming/naming-naming-convention.en.md.

introduction.*.md est acceptable comme nom de fichier dans une série parce qu’il donne une première page prévisible. Le titre rendu de la page doit tout de même être compréhensible seul dans les listes globales, les flux, la recherche et le sitemap. N’utilisez pas title: "Introduction" pour une page publiée; utilisez un titre précis et gardez weight: -100 pour l’ordre.

URL de liens courts#

La section Liens utilise une structure d’URL courtes en deux étapes: une URL concise à partager, qui mesure d’abord le passage sur ce site avant que le lecteur quitte vers la page externe.

Chaque entrée de data/links.yml conserve un seul jeton de routage, slug. Le layout dérive chaque URL courte de ce jeton avec des préfixes codés en dur; ne stockez pas les valeurs dérivées comme linkShortURL ou linkExtShortURL dans le fichier de données.

Règles pour les slugs:

• un seul jeton par entrée, partagé par la page locale et les deux URL courtes
• quatre caractères aléatoires tirés de l’alphabet lisible de vanityURLs quand le jeton n’est pas défini manuellement
• les jetons existants restent stables; renommer un slug casse les URL courtes publiées

Le registre des URL courtes vit dans custom/v8s-links.txt dans l’instance vanityURLs dicai-re. Chaque item possède deux entrées jumelées qui partagent le même jeton:

L’entrée l/ indique sa paire avec external=https://dicai.re/lnk/<slug>, et l’entrée lnk/ indique sa paire avec link=https://dicai.re/l/<slug>; le registre reste facile à balayer sans stocker les longues URL externes dans le champ notes. npm run links normalise le fichier de données et met à jour les entrées jumelées; npm run check:links valide le registre après une modification.