Configuration

Tout ce qui suit vit sous duxt dans votre app/app.config.ts. Le fonctionnement de la fusion, et pourquoi les tableaux remplacent au lieu de s’ajouter, est dans Configuration.

#Site

#logo

En définir un, c'est Donner son identité à votre site.

#organization

Le nœud Organization que les moteurs de recherche et les résumés d'IA lisent pour nommer une source. Absent tant que vous ne le définissez pas : duxt rend la documentation d'autrui et ne devine pas de qui.

#Navigation et liens

Une entrée de section est un lien, plus un champ qui lui est propre :

Utile là où une page ne peut porter aucune icône — le frontmatter d'un ADR est figé à title, description, status et date, si bien que le journal des décisions s'afficherait sans.

La plupart sont livrés vides, pour deux raisons différentes. links, aside.links, footer.legal, title, version et le texte de la page d’accueil désignent un projet précis — un dépôt, une communauté, des mentions légales, un nom, une version publiée, une phrase sur ce qu’il fait — et appartiennent à qui exploite le site. sections nomme les parties d’une arborescence de documentation, et l’arborescence est la vôtre : quatre onglets pointant vers des noms de dossier devinés par la couche ne mèneraient nulle part. Définissez-le une fois que votre documentation a des sections ; d’ici là, la rangée ne s’affiche pas et la barre latérale montre l’arbre entier, ce qui est la bonne forme pour une documentation sans sections.

Une rangée par source. Une entrée appartient à la source sous le préfixe d’URL de laquelle elle se trouve, et la rangée affiche les entrées de la source où se trouve le lecteur — un site dont la documentation est à la racine et qui publie autre chose sous /demo écrit donc une seule liste sections, et chaque zone y dessine sa part. Une section générée sous une zone (/demo/api) appartient à cette zone plutôt que d’en être une. Un site à source unique a une zone, chaque entrée y est, et la rangée est exactement la liste écrite.

#Page d’accueil

La page à / dessine trois bandes, et chacune est absente tant que sa clé n’est pas définie.

command est une simple string, pas du texte : une commande shell est identique dans toutes les langues, et une commande traduite par erreur ne s’exécute pas. La couche n’en livre aucune — elle ne sait pas comment s’appelle votre projet, pour la même raison que links est vide.

Il n’y a délibérément pas d’appel à l’action final. Les boutons du bloc principal sont l’appel ; les répéter sous une grille de cartes demande à un lecteur qui vient d’arriver de décider deux fois.

badge est livré vide pour la même raison que links : une pastille au-dessus du titre dit quelque chose de l’état d’un projet — « beta », « v2 est sortie » — et la couche ne sait rien de l’état du vôtre. Une chaîne est la forme courte ; l’objet ajoute une icône, une couleur et une destination.

badge: {
  label: '{version} publiée',
  icon: 'lucide:rocket',
  variant: 'success',
  to: 'https://github.com/acme/sdk/releases/latest',
  external: true
}

preview est une fenêtre vivante, pas une image. Elle intègre une page de ce site dans un cadre de navigateur que le lecteur peut faire défiler, parcourir et dont il peut changer le thème sans quitter la page d’accueil. Le cadre n’est monté qu’une fois la bande visible, et jamais pendant le rendu serveur — une iframe dans le HTML initial, c’est un second chargement complet en concurrence avec le premier.

#Forme d’un lien

Tout champ marqué texte accepte un littéral, une clé i18n ou un enregistrement par locale — voir Localisation.

#Sources

Les deux clés de source ont leur propre page. locales est la troisième clé lue à la compilation : modifier l’une des trois impose une recompilation.

#Le flux

/rss.xml est vide tant que feed.path ne nomme pas une section :

feed: { path: '/changelog', title: 'mon projet — publications' }

Désactivé par défaut, à dessein. Un flux est une liste de choses qui se sont produites, et une page de référence modifiée n’est pas un événement — un site qui publie chaque modification comme élément apprend à ses lecteurs à se désabonner. Les éléments sont ordonnés par la date propre à la page, à défaut par le dernier commit qui l’a touchée, et seule la version par défaut de chaque source contribue : un changelog versionné ne répète donc pas chaque entrée une fois par version.

La section vers laquelle il pointe d’ordinaire est un journal des versions, dont les pages portent chacune une date.

#Généré, pas écrit

Définir l’un des trois à la main est écrasé à la compilation suivante.