Configuration

La configuration du site réside dans site.toml à la racine source. Juicer superpose votre fichier par-dessus l’une de trois bases (simple, standard, norme) sélectionnée par l’option CLI -c <name>.

Bases

Clés

Identité

Thème

Disposition des répertoires

Le parcours saute déjà les sous-dossiers du themeDir actif, le parent du themeDir (pour que les thèmes inactifs rangés à côté ne se rendent pas), le publicDir configuré et le dst de sortie de la construction. Utilisez excludeDirs pour tout le reste sous la racine source qui ne fait pas partie du site — outillage rangé, dossiers de brouillon, ressources générées que vous produisez hors bande, brouillons gardés hors de content/ :

excludeDirs = ["node_modules", "scratch", "assets/raw"]

Noms de layout

Comportement

Navigation — nav

Tableau de premier niveau qui pilote .site.toc (la navigation latérale / barre supérieure). Quand nav est absent, juicer construit automatiquement la navigation en parcourant l’arborescence de contenu. Quand nav est défini, juicer parcourt les entrées du tableau :

• Une chaîne se terminant par une extension markdown (.md, .markdown, .mkd, .mkdn, .mdown) est une référence à un fichier de contenu (chemin relatif à contentDir). L’enregistrement de page à ce chemin est tiré dans la navigation à la position du tableau.
• Toute autre chaîne est un libellé de section — un titre de groupe non cliquable.
• Une table à clé unique associe un libellé explicite à un chemin de contenu — utile quand le titre du frontmatter du fichier n’est pas le bon libellé pour la navigation.

nav = [
  "Getting Started",                       # label# label
  "getting-started/_index.md",             # link, title from frontmatter# link, title from frontmatter
  "getting-started/installation.md",
  { "Get help" = "getting-started/troubleshooting.md" },   # link, explicit label# link, explicit label
  "Reference",                             # label# label
  "reference/cli.md",
  "reference/config.md",
]

Le même tableau est aussi parcouru par les partials « précédent / suivant » des thèmes quand nav est défini, donc l’ordre que vous écrivez ici est l’ordre dans lequel les lecteurs feuillettent.

i18n — languages, defaultLanguage

Deux clés optionnelles qui activent le mode multilingue. Le moteur ne duplique pas le contenu pour vous (un fichier markdown par langue reste la convention) — il fait remonter la langue active aux gabarits pour que les thèmes puissent rendre un habillage conscient de la langue et tirer des chaînes d’une table de traduction.

Les chaînes de traduction résident dans <src>/i18n/<lang>.toml, un fichier par langue déclarée, sous forme de tables plates clé = "valeur" :

# i18n/en.toml# i18n/en.toml
home          = "Home"
browse_docs   = "Browse the docs"
read_more     = "Read more"

# i18n/fr.toml# i18n/fr.toml
home          = "Accueil"
browse_docs   = "Parcourir la documentation"
read_more     = "Lire la suite"

Les gabarits recherchent les chaînes avec l’assistant i18n, en passant la langue de la page :

<a href="/">{{ i18n .page.lang 'home' }}</a>
<a href="/docs/">{{ i18n .page.lang 'browse_docs' }}</a>

Les recherches retombent sur defaultLanguage quand une clé manque dans la langue demandée ; si la clé manque dans les deux, la clé littérale est renvoyée (pour qu’une traduction manquante soit visible pendant la rédaction sans faire planter la construction).

Fonctionnalités de blogue

Ces clés activent les fonctionnalités de blogue documentées sous Concepts → Fonctionnalités de blogue. Les quatre sont optionnelles ; un site de documentation qui ne les définit pas se rend inchangé.

Fonctionnalités de calendrier / événements

Juicer fait remonter une liste d’événements organisée (.site.events) et une grille de calendrier sur 12 mois (.site.calendar) pour tout site ayant une section de pages d’événements. Voir Données de gabarit → .site.events et .site.calendar.

Les événements récurrents relèvent du thème et du gabarit — le moteur reconnaît un frontmatter recurring: weekly plus un recurringDay: optionnel sur les pages d’événement et déploie l’événement sur chaque jour de semaine correspondant dans .site.calendar. Sans recurringDay:, la récurrence retombe sur le jour de la semaine de la date de début.

[permalinks] — gabarits d’URL par section

Une sous-table TOML qui supplante le motif d’URL d’une section. Chaque clé est un nom de section (le premier segment de chemin après le retrait de htmlDir) ; chaque valeur est une chaîne de gabarit avec des jetons de substitution. Les jetons sont résolus contre le frontmatter et la date analysée de la page.

[permalinks]
posts = ":year/:month/:slug/"
notes = ":slug/"
articles = ":year/:section/:title/"

Jetons reconnus :

Les sections sans entrée [permalinks] gardent l’URL par défaut dérivée du chemin physique de juicer (l’arborescence de fichiers détermine l’URL un pour un). Les pages d’index de section (_index.md) ne sont jamais routées par les gabarits de permalien — elles résident toujours à la racine de la section.

Voir Concepts → Fonctionnalités de blogue → Permaliens pour la version narrative.

[comments] — emplacement de configuration du fournisseur de commentaires

juicer ne livre jamais de backend de commentaires. Les sites qui veulent des commentaires déclarent le fournisseur et les clés propres au fournisseur sous [comments] dans site.toml ; les partials de thème relisent la configuration comme .site.comments.* et émettent le bon HTML d’intégration.

[comments]
provider = "giscus"
repo     = "edadma/juicer"
repoId   = "R_kgDOXXXXXX"
category = "Announcements"
categoryId = "DIC_kwDOXXXXXX"
mapping  = "pathname"
reactions = true
theme    = "preferred_color_scheme"

La seule convention qui intéresse le moteur est le nom de la table lui-même — tout ce qui est à l’intérieur est opaque pour juicer. Clés conventionnelles pour les fournisseurs courants :

Les thèmes conditionnent typiquement l’intégration sur {{ if .site.comments }} et sur une surcharge de frontmatter par page comments: false (pour que des articles individuels puissent renoncer aux commentaires sans désactiver la configuration du site). Voir Données de gabarit → .site.comments pour le contrat côté gabarit.

[images] — génération de variantes d’image

Génération optionnelle au moment de la construction de variantes d’image redimensionnées + reformatées (webp, avif, etc.) pour un balisage <picture> / <img srcset> adaptatif. La fonctionnalité est désactivée par défaut — les sites qui ne définissent pas cette table se construisent à l’octet près comme avant [images].

[images]
enabled  = true
widths   = [320, 640, 960, 1280]
formats  = ["webp", "original"]   # most-modern first; "original" passes through# most-modern first; "original" passes through
quality  = 80
cacheDir = ".image-cache"          # under dst; variants land here# under dst; variants land here

Encodeur. Juicer appelle ImageMagick (magick) — installez avec brew install imagemagick / apt install imagemagick / dnf install ImageMagick. Quand magick n’est pas dans le PATH, la construction réussit quand même, mais imageVariants renvoie un ensemble de transmission seulement (une seule ligne d’avis s’affiche sur stderr). Les cibles Scala Native et Scala.js livrent un backend de remplacement ; la génération complète de variantes est aujourd’hui réservée à la JVM.

Côté gabarit : voir Syntaxe de gabarit → imageVariants et srcset pour les assistants que les thèmes appellent.

[assets] — pipeline Sass / esbuild

Compilation optionnelle au moment de la construction des ressources de thème via deux CLI largement disponibles : sass pour SCSS → CSS et esbuild pour le regroupement et la minification du JS. Plus une option d’empreinte optionnelle qui ajoute un hachage de contenu aux noms de fichiers de sortie pour que les déploiements puissent livrer des URL anti-cache sans renoncer aux en-têtes Cache-Control à longue durée de vie. Désactivé par défaut — les sites qui ne définissent pas cette table se construisent à l’octet près comme avant [assets].

[assets]
enabled     = true
fingerprint = false

[[assets.sass]]
input  = "src/site.scss"
output = "/css/site.css"
minify = true

[[assets.esbuild]]
input  = "src/main.js"
output = "/js/main.js"
minify = true

[[assets.copy]]
input  = "src/robots.txt"
output = "/robots.txt"

Tables d’entrée (n’importe quel nombre de chacune ; utilisez la forme abrégée de table en ligne ou la forme tableau [[assets.kind]]) :

input est résolu sous la racine source ; output est un chemin d’URL enraciné au site (barre oblique de tête optionnelle). logical retombe par défaut sur le nom de base de output — /css/site.css devient la clé de manifeste site.css, que les gabarits recherchent comme {{ asset 'site.css' }}.

Installation des outils. Juicer appelle sass (le paquet npm dart-sass ; la gem Ruby sass fonctionne aussi pour le petit sous-ensemble d’options que juicer utilise) et esbuild. Installez avec brew install sass esbuild / npm install -g sass esbuild / l’équivalent de votre plateforme. Quand un outil n’est pas dans le PATH, la construction réussit quand même : cette entrée se dégrade en une copie telle quelle de sa source, l’URL se résout toujours pour que les gabarits ne cassent pas, et une seule ligne d’avis va sur stderr. Les cibles Native et JS livrent des backends de remplacement ; l’exécution complète du pipeline est aujourd’hui réservée à la JVM.

Côté gabarit : voir Données de gabarit → builtin asset.

[[authors]] — registre d’auteurs

Un tableau de tables décrivant les personnes qui écrivent des articles sur le site. Chaque entrée a besoin d’au moins un id ; tout le reste est optionnel et s’écoule directement dans les enregistrements .page.author / .page.authors.

[[authors]]
id     = "ed"
name   = "Edward A Maxedon"
email  = "ed@example.com"
bio    = "Writes a lot of code."
avatar = "/img/ed.jpg"

[[authors.links]]
label = "GitHub"
url   = "https://github.com/edadma"

Les pages référencent un auteur via author: <id> ou authors: [<id>, ...] dans leur frontmatter. Voir Concepts → Fonctionnalités de blogue → Registre d’auteurs pour la narration complète.

Clés personnalisées

Toute clé que vous définissez dans site.toml est disponible comme .site.<key> dans les gabarits. Utilisez ceci pour les réglages à l’échelle du site que le thème expose — p. ex. editURL, discussionURL, social.twitter. Les thèmes documentent typiquement les clés qu’ils reconnaissent dans leur README.