Personnaliser le rendu

notabene s’exécute depuis le paquet — vous ne forkez jamais son UI. Tout ce qui suit passe par la config à la place :

1. Branding — logo, favicon, image sociale.
2. Tokens — surchargez les custom properties --nb-* (ci-dessous).
3. Votre propre feuille de style — un fichier CSS chargé après les styles du renderer.
4. Polices et images — un dossier de votre repo, servi pour cette feuille de style.
5. Code et diagrammes — un thème Shiki pour les blocs de code ; Mermaid suit les tokens.

Les liens sortants (topbar, sidebar, pied de page) n’en font pas partie : ce sont des données du dépôt, pas de l’apparence — voir liens de navigation.

theme: {
  // Surcharges rapides, aucun fichier requis. Une valeur simple s'applique aux DEUX schémas ;
  // une paire light-dark() personnalise chacun : clair à gauche, sombre à droite.
  tokens: { accent: "light-dark(#7c3aed, #b79bff)", radius: "4px" },
  css: "docs/notabene-theme.css",                 // ou/et une feuille de style complète
},

Les deux ciblent le même contrat ; un nom de token mal orthographié lève une erreur au démarrage (jamais un no-op silencieux). Les styles du renderer vivent dans des cascade layers CSS, donc votre CSS hors layer gagne toujours — pas de guerre de spécificité, pas de loterie d’ordre.

Tout suit cette palette — le chrome, les blocs de code et les diagrammes — et le sélecteur de schéma de l’en-tête la bascule en direct, sans rebuild :

Diagrammes

Les diagrammes Mermaid suivent les tokens d’emblée : les nœuds sont remplis en accent-soft et bordés d’accent, les libellés utilisent la couleur du texte, les arêtes text-soft — et ils se re-rendent au changement de schéma, donc un diagramme en mode sombre est un vrai diagramme sombre, pas une image inversée. Rien à configurer.

Si un diagramme rend mieux avec la palette de Mermaid, désactivez :

theme: { mermaid: false },   // retour aux thèmes default/dark intégrés de Mermaid

Coloration syntaxique (theme.code)

Les blocs de code sont colorés au build : leurs couleurs sont donc figées — d’où le décalage habituel, un thème clair avec des blocs de code sombres. Nommez un thème Shiki et cela change :

theme: {
  code: "github-light",                            // même thème dans les deux schémas
  // ou un par schéma :
  code: { light: "github-light", dark: "vesper" },
},

• Avec code, les deux palettes voyagent en variables CSS et le sélecteur de schéma recolore le code instantanément — sans rebuild, sans clignotement.
• Le thème de code prend alors aussi la main sur le fond du bloc (les tokens d’un thème clair sur la dalle sombre par défaut seraient illisibles). --nb-code-bg reste le fond pour quiconque ne définit pas theme.code.
• Le PDF/print force le schéma clair : c’est donc votre thème de code clair qui atterrit sur le papier.
• Nom de thème inconnu → erreur au démarrage, comme pour chaque réglage de thème.

Polices et images (theme.assets)

Une feuille de style a généralement besoin de fichiers : une police web, un fond, une texture. Pointez theme.assets vers un dossier de votre repo : il est servi au chemin fixe /_nb/assets/… — en dev, dans les builds et dans les artefacts publics, pour qu’un site publié reste autonome (pas de CDN) :

theme: { css: "docs/theme/site.css", assets: "docs/theme/assets" },

/* docs/theme/site.css */
@font-face {
  font-family: "Inter";
  src: url("./assets/fonts/Inter.woff2") format("woff2");   /* ← relatif, toujours */
}
:root { --nb-sans: "Inter", system-ui, sans-serif; }

• Écrivez les url() en relatif, jamais en absolu depuis la racine. Les URL se résolvent contre la feuille servie (/_nb/theme.css), pas contre votre fichier source — donc ./assets/… est la forme correcte, et elle absorbe gratuitement un sous-chemin base (site projet GitHub Pages), là où /_nb/… casserait.
• Déclarez un dossier dédié, pas docs/ : tout ce qui y est servable est émis, référencé ou non.
• Seuls des assets sont servis — polices (woff2, woff, ttf, otf), images (svg, png, jpg, webp, avif, gif, ico) et css. Tout le reste (.md, .env, scripts), chaque fichier caché et tout lien symbolique pointant hors du dossier sont refusés.

Le contrat de tokens (--nb-*)

Ces custom properties sont la surface de theming publique — stable d’une version à l’autre. Les défauts de couleur sont donnés sous leur paire light-dark(light, dark) :

Chaque token de couleur est une paire light-dark() — une seule déclaration couvre les deux schémas, et le sélecteur clair/sombre de l’en-tête (auto / clair / sombre, persisté par navigateur) les bascule tous d’un coup. Un thème qui change les couleurs fait de même :

/* docs/notabene-theme.css */
:root {
  --nb-accent: light-dark(#7c3aed, #b79bff);
  --nb-accent-soft: light-dark(#f1e9ff, #241a3d);
}

Le sélecteur fonctionne via color-scheme + un attribut data-scheme que le renderer pose sur <html> — un thème ne doit pas définir cet attribut (ni color-scheme sur :root) ; surchargez des tokens, et le sélecteur continue de fonctionner sans effort. light-dark() ne couvre que les couleurs ; pour le rare style par schéma hors couleur, sélectionner sur :root[data-scheme="dark"] dans votre feuille de style est très bien — c’est poser l’attribut qui est réservé.

Au-delà des tokens

Votre feuille de style peut aussi cibler un petit ensemble de points d’accroche stables : .topbar, .brand, .sidebar, .prose (le contenu rendu), .home-cards, .rail, plus les liens de navigation — .nb-nav-link (tout lien sortant), .nb-sidebar-links (le bloc sous l’arbre des espaces) et .site-footer. Tout le reste — et chaque variable CSS sans préfixe — est interne et peut changer d’une version à l’autre.

Un thème style ces liens ; il n’en déclare jamais. Les entrées de nav, le texte du pied de page et les assets de branding sont des données du dépôt (nav, branding au premier niveau de la config), pas de l’apparence : une feuille de style installée ne doit pas pouvoir injecter des liens sortants dans un site publié, ni porter des libellés dans des langues qu’elle ne peut pas connaître.

Deux règles vous gardent en sécurité :

• Ne surchargez que les tokens --nb-* et les points d’accroche ci-dessus. En particulier, ne touchez jamais aux variables sans préfixe : les vues print/PDF forcent une palette claire à travers elles, donc un thème limité aux tokens peut restyler tout le site sans jamais casser l’export PDF.
• Vérifiez les deux schémas de couleur — le sélecteur de l’en-tête en fait un test à deux clics.

Les thèmes s’appliquent partout : dev, builds normaux, sites publics et les vues print (couleurs exceptées, à dessein).