Mise en page de documentation

Tâche#

Utilisez ce motif pour la documentation de marque qui a besoin d’une orientation persistante sans sacrifier l’espace de lecture horizontal. Il aide une personne à comprendre où se trouve une page, à la lire dans un seul flux principal et à poursuivre vers une page liée de façon intentionnelle.

Composition#

La mise en page combine la Barre latérale de documentation, le Fil d’Ariane, un bloc de titre de documentation, le contenu de l’article et les Pages liées facultatives. La structure de documentation possède leur ordre et leur largeur; chaque composant conserve son propre contrat de comportement.

Contenu et données#

La barre latérale lit l’arborescence de documentation bilingue depuis les sections et les pages Hugo. Chaque page fournit le front matter standard — titre, description, date et lastmod — pour son bloc de titre, ses index et ses rangées liées. Ajoutez related: seulement lorsqu’une personne a une prochaine destination utile; ne l’utilisez pas comme liste générale d’étiquettes.

Comportement adaptatif#

Sur les écrans larges, la barre latérale de documentation occupe la colonne de gauche et l’article reçoit la largeur de lecture restante. Aux petites tailles, la colonne devient partie du flux normal du document et reste disponible avant l’article. Il n’y a intentionnellement aucune table des matières persistante à droite.

Implémentation#

layouts/partials/docs/shell.html compose la structure une fois pour la section de documentation. Il fournit les sections et la page courante à la barre latérale, émet le fil d’Ariane avant l’article, rend le bloc de titre et le contenu, puis place les pages liées à la fin. La barre latérale utilise des éléments de divulgation natifs et un petit script seulement pour empêcher qu’un lien de section dans son résumé bascule accidentellement la divulgation.

Accessibilité#

• La barre latérale et le fil d’Ariane sont des points de repère de navigation nommés distincts; aucun ne remplace l’autre.
• L’article reste un seul flux de lecture principal, sans table des matières à droite qui rivalise pour la largeur ou le focus.
• La barre latérale utilise <details> et <summary> natifs pour la divulgation, et la page courante utilise aria-current="page".
• Le fil d’Ariane utilise une liste ordonnée et un élément de page courante non lié. Les pages liées sont des liens ordinaires dans une région complémentaire nommée.
• Aux petites tailles, l’ordre source garde les outils d’orientation disponibles avant le contenu de l’article plutôt que de dépendre d’un réarrangement uniquement visuel.