Admonition

Une admonition met un passage à part et dit comment le lire : un conseil, une mise en garde, un danger. Six types sont livrés avec l'outil, et un projet déclare les siens plutôt que d'attendre que cette liste grandisse.

Les six types

<Admonition type="tip">Un raccourci, une habitude à prendre.</Admonition>

Sans type, le bloc est une note.

Un titre à soi

<Admonition type="attention" title="À lire avant de mettre à jour">
  …
</Admonition>

Des types à vous

Un type est un libellé et un ton. Le ton porte la couleur, prise au thème : un nouveau type ne demande donc aucune feuille de style et suit le thème actif, quel qu'il soit.

// docpensieve.config.mjs
admonitions: {
  review: { label: 'À relire', tone: 'attention' },
  legal: { label: 'Mention légale', tone: 'info' },
},

<Admonition type="review">Cette section attend une seconde paire d'yeux.</Admonition>

Une marque à soi

Un type peut porter une icône à la place du dessin de son ton — le logo d'un outil, la marque d'une équipe. Il nomme un SVG du dossier de version, ou une icône d'un jeu, et les deux sont posés dans la page à la génération :

admonitions: {
  review: { label: 'À relire', tone: 'attention', icon: '/icons/review.svg' },
  shipped: { label: 'Livré', tone: 'tip', icon: 'simple-icons:github' },
},

Un fichier qui n'existe pas arrête la génération, en nommant le chemin cherché. Un jeu d'icônes est un paquet que le projet installe — voir LogoIcon — et un jeu absent l'arrête aussi.

Les tons sont note, info, tip, attention et danger. Un type que personne n'a déclaré arrête la génération, en listant ceux qui existent : rendu quand même, le bloc sortirait sans couleur ni libellé, et rien ne dirait pourquoi.

Mise en forme

Le bloc prend ses couleurs aux jetons du thème — --dp-tip, --dp-attention, --dp-danger et leurs fonds -soft — et suit donc les schémas clair et sombre tout seul.

Un className ajoute des utilitaires par-dessus :

<Admonition type="tip" className="shadow-sm">
  …
</Admonition>

Ce qu'elle porte

Un bloc contient ce que contient une page — plusieurs paragraphes, une liste, un bloc de code :

Sans JavaScript

Comme tous les composants d'ici, elle est rendue à la génération. C'est un aside annoncé comme une note, avec son icône masquée aux lecteurs d'écran — le titre à côté dit déjà le type, et le dire deux fois n'aide personne.