Barre latérale de documentation
La barre latérale de documentation est la navigation générée dans le rail gauche de /docs/. Elle expose la hiérarchie de la documentation, garde la branche courante ouverte et marque la page courante sans prendre l’espace de l’article avec une table des matières à droite.
Cette page rend le composant en direct dans le rail à sa gauche.
Exemple#
Variantes#
- La racine de la documentation forme un groupe Survol distinct; les pages avec
docs_overview_link: trues’affichent sous ce groupe - La profondeur 0 utilise des libellés de groupe en majuscules; les groupes et pages imbriqués gardent le même traitement compact de ligne
- Les branches actives sont ouvertes; la page courante ajoute
aria-current="page"et le marqueur d’accent
Quand l’utiliser#
- Une seule fois dans le gabarit de documentation, sur les pages sous
/docs/ - Pour parcourir l’arborescence de documentation et passer entre sections ou pages voisines
- Jamais comme table des matières d’une page ou comme remplacement de la navigation générale du site
Comparaison avec l’index d’ancrage#
| Aspect | Barre latérale de documentation | Index d’ancrage |
|---|---|---|
| Portée | L’arborescence de documentation entre les pages | Les sections répétées de la page courante |
| Source de données | Les sections et pages Hugo | Une liste items fournie par l’appelant |
| Destination | Des URL localisées de pages | Des identifiants de fragment comme #accessibilite |
| Divulgation | L’état natif de <details>; la branche active commence ouverte | Aucun état de divulgation |
| JavaScript | Aucun | Aucun |
| Usage approprié | Une orientation persistante dans la documentation | Des raccourcis dans une longue page structurée |
Aucun des deux composants ne filtre le contenu. Une rangée de filtres modifie ce qui apparaît; ces composants déplacent seulement la lectrice ou le lecteur vers du contenu déjà présent.
Implémentation#
layouts/partials/docs/shell.html fournit la section docs et la page courante, puis appelle la barre latérale une fois :
{{ partial "docs/sidebar.html" (dict "Page" . "Sections" $sections) }}sidebar.html rend le groupe Survol et chaque section de premier niveau de la documentation. sidebar-section.html parcourt récursivement les sections et pages régulières descendantes. Le gabarit fournit les sections de premier niveau dans l’ordre de poids; les éléments imbriqués sont triés par titre. Une section qui contient la page courante commence avec son élément <details> natif ouvert.
Le CSS dans assets/css/site.css fournit le rail fixe et défilable, le traitement de profondeur, de divulgation et d’état actif, ainsi que la disposition compacte sur petit écran. Le nom du point de repère de navigation vient de la clé i18n brandDocsSidebarLabel. Chaque sommaire natif contient du texte ordinaire et un chevron décoratif; le premier lien de son panneau mène au survol de la section.
Manifeste d’interface
- Nature
- Composant
- Catégorie
- Navigation
- Statut
- Implémenté
- Implémentation
- Partial:
layouts/partials/docs/sidebar.htmllayouts/partials/docs/sidebar-section.htmlCSS:assets/css/site.cssi18n:brandDocsSidebarLabelbrandDocsOverviewbrandDocsSectionOverview - Utilisé par
layouts/partials/docs/shell.html- Interfaces liées
- Index d’ancrageFil d’ArianeNavigation
Accessibilité#
- Le
<nav>porte le libellé localisébrandDocsSidebarLabel, ce qui distingue ce point de repère de navigation de la navigation d’en-tête, du sélecteur de langue et du fil d’Ariane - Les sections utilisent les éléments natifs
<details>et<summary>plutôt qu’un ARIA de divulgation personnalisé; la branche active est ouverte dans le HTML rendu - Un sommaire ne contient aucun lien ni autre descendant interactif; le lien vers le survol de la section est le premier élément du panneau divulgué
- Chaque destination est un lien ordinaire; la page courante porte
aria-current="page"et le marqueur d’accent est seulement un renforcement visuel - Le SVG du chevron est
aria-hidden="true"; il n’ajoute pas une annonce redondante au libellé de section - Les personnes qui utilisent le clavier peuvent suivre les liens dans l’ordre de lecture et utiliser le contrôle de divulgation natif pour ouvrir ou fermer une section