Mise en page et composants

Le type changelog écrit des pages Markdown ordinaires dont les corps sont deux composants MDC, rendus dans une mise en page à eux. Les trois sont documentés parce qu’ils font partie de la surface publique — un consommateur peut remplacer n’importe lequel — non parce qu’une page devrait être écrite à la main.

#La mise en page changelog

Liée à la seule granularité split ; un journal plat est une page de documentation ordinaire et se rend dans le cadre de la documentation.

Elle diffère de docs sur deux points, et les deux découlent de ce que sont les pages. La barre latérale est la liste des versions plutôt qu’un arbre de prose — même navigation, même collection, parce qu’une section générée est une collection ordinaire et que ses pages sont les versions. Et la colonne de lecture est bornée à une mesure : une note de version est de la prose, et de la prose composée sur toute la fenêtre est illisible. La colonne de sommaire reste, listant les groupes.

Remplacez-la par un fichier à vous au même chemin :

app/layouts/changelog.vue

#ChangelogReleases

La chronologie de la vue d’ensemble : chaque version, la plus récente d’abord, filtrable par ce qui a changé. Écrit sur la page d’index de la section.

L’historique s’ouvre sur quatre chiffres : versions, changements, contributeurs et date de la dernière publication, dans une grille de quatre colonnes sur toute la largeur. La date est la seule valeur qui ne soit pas un compte ; si le fichier ne date rien, elle est omise plutôt que remplacée par un tiret. Ces chiffres indiquent l’ampleur de l’historique, ce que ses lignes seules ne peuvent faire. Ils comptent ce qui est affiché : après filtrage, ils décrivent la page filtrée, avec le total conservé à côté du premier chiffre ; filtré sur les changements cassants, le nombre de contributeurs dit qui en a déjà livré un.

#D’où viennent les contributeurs

Pas du changelog, mais de la plage git entre le tag précédent et cette version. 1.2.0 et v1.2.0 sont tous deux essayés. Les commits de fusion fixent les limites sans recevoir de crédit comme changement propre ; les comptes marqués comme apps sont exclus.

Le libellé porte l’accent, pas le chiffre : --primary est la couleur qu’un site consommateur choisit pour personnaliser le thème, et deux courtes lignes de libellé peuvent la porter sans coût visuel.

En dessous, chaque version tient sur une ligne en colonnes : version, badge, contenu, date. Les versions s’alignent et les résumés commencent au même endroit. Sous sm, le résumé passe à la ligne ; rien ne défile horizontalement. Le badge de version courante reste à côté du numéro, dans une colonne fixe qui existe même vide, afin que les résumés des versions sans badge commencent au même endroit. La date est à l’extrémité, près de la flèche : le lecteur parcourt ce champ verticalement plutôt que de le lire dans la longueur de la ligne.

Le filtrage anime les deux côtés : les pastilles qui apparaissent au-dessus et les lignes qui bougent en dessous, avec les mêmes durées pour former un seul geste. Les lignes s’estompent et se placent en 200 ms ; une ligne sortante quitte le flux pour que les suivantes referment l’espace pendant sa disparition. Le FLIP du navigateur déplace celles qui restent. C’est une TransitionGroup, sans bibliothèque d’animation : un fondu et un léger déplacement ne justifient pas une dépendance d’exécution dans chaque site consommateur. Tout est désactivé sous prefers-reduced-motion. Une ligne nomme les trois plus grands groupes et compte les autres : « Features 2 · Bug Fixes 2 · Documentation 1 · et 9 autres ». Trois, par nombre, pas selon l’ordre fixe des sections de release-please, qui n’exprime aucune importance. Rien n’est omis en silence ; une ligne filtrée nomme d’abord ce sur quoi porte le filtre.

La couleur reste là où elle distingue plutôt qu’elle ne décore : dans le menu de filtre et le libellé de chaque groupe sur la page de version, pas dans l’historique.

Une marque devant un nom est retirée à l’affichage, partout où le nom apparaît : le ⚠ précédant le bloc de changements cassants de release-please ou un emoji ouvrant une section manuscrite. Seulement au début, pour conserver C++ Support. Le nom stocké reste entier : le filtre le compare, l’ancre en est dérivée et les props le portent. Le retrait appartient donc à l’affichage, pas à l’analyseur. Voir changelogLabel.

Les groups d’une version ne portent qu’un name et un count — les entrées ne sont pas ici, parce que chaque version a une page à elle et que répéter ses puces mettrait l’historique entier deux fois dans l’index de recherche, dans llms-full.txt et dans le flux.

Les pastilles de filtre sont construites à partir des noms que le fichier a lui-même employés. Sans sélection, la page montre tout, ce qui est aussi ce que rend le serveur : un filtre est le choix d’un lecteur, la page doit donc être complète avant que quiconque en fasse un — sinon le robot d’indexation et le lecteur dont l’hydratation n’est pas encore arrivée se voient chacun servir un journal filtré que personne n’a demandé.

#ChangelogGroup

Un groupe d’une version — « Features », « Bug Fixes », ce que le fichier disait.

Les entrées arrivent dans le slot, comme le Markdown qu’elles ont été écrites — ainsi la recherche les indexe, llms-full.txt les porte et le bouton de copie remet à un modèle de la prose plutôt qu’un appel de composant. Seuls le nom et le nombre, dont le badge et les filtres ont besoin comme données, voyagent en props.

Le nom est un libellé, pas un gros titre : petit, en majuscules et dans la teinte du groupe, au-dessus d’une liste resserrée. À 20 pixels, ce mot désignant quatre puces prenait le poids d’un chapitre, et six groupes semblaient six sections plutôt qu’une version. Il reste un <h2> : plan, colonne de sommaire et ancre ne changent pas ; seule la composition ajuste son importance visuelle.

La couleur est un indice et jamais un sens : un nom inconnu reçoit sa propre couleur stable, rendant le même type de changement repérable sur une page de quarante versions dans toute langue. Le libellé utilise la paire text de la teinte plutôt que son remplissage dot : des mots et un point de six pixels n’atteignent pas le contraste requis à la même luminosité.

Les marqueurs des entrées restent gris. La couleur figure déjà dans le libellé au-dessus ; répétée à chaque ligne, elle cesse d’être un signal. Les marqueurs sont définis dans duxt.css, pas dans ce composant, car ils arrivent comme Markdown par le slot.

#En remplacer un

Comme pour tout autre composant que la couche livre : un fichier au même chemin dans le site consommateur l’emporte.

app/components/content/ChangelogGroup.vue

Les props ci-dessus sont le contrat, et le nom de la mise en page aussi. Un renommage ici est un changement cassant de la couche.

#Ce qu’une page de version montre en plus des groupes

Rien dans le corps. La date de publication et le diff dont la version est issue voyagent dans les champs date et compare du frontmatter. Ils apparaissent là où le site indique déjà l’origine d’une page : le bloc de provenance sous la colonne de sommaire, au-dessus de « Modifier cette page ».

La date de version remplace la ligne du dernier commit : toutes les versions d’un journal vivent dans un fichier, dont le dernier commit leur donnerait à toutes la même date — au mieux celle de la plus récente.

Une page de version se lit ainsi comme toute autre page Markdown du site : une note de version est de la prose, pas un tableau de bord.

#Pas de titre à eux

Aucun des deux composants n’ouvre sur un <h1>. Le cadre de la documentation dessine l’en-tête — fil d’Ariane, titre, le bouton de copie à côté — pour toute page générée dont le corps n’ouvre sur aucun titre, et une page de version veut exactement cela : un titre et une trace comme toute page écrite.