Données de gabarit

Chaque gabarit se rend contre une seule carte. Les clés de premier niveau sont documentées ci-dessous ; les champs imbriqués suivent.

.site

La configuration de site fusionnée (site.toml superposé sur la base) plus quelques extras calculés :

Forme de Term

Chaque entrée de .site.tags et .site.categories (et sur les gabarits d’archive de mots-clés, les éléments de .terms) a ces champs :

.site.posts et .site.pagesByYear

Vues organisées du flux d’articles — les mêmes données, découpées de deux façons.

.site.posts est la liste plate, plus récent d’abord. Une page est incluse si elle a une date: analysée explicite dans le frontmatter, n’est pas un index de section (_index.md), et n’est pas marquée static: true. Les dates issues du repli sur la mtime du système de fichiers ne comptent pas — seules les dates rédigées y entrent. Le résultat est exactement l’ensemble de pages qu’un blogue ou un site d’actualités appellerait « les articles ».

.site.pagesByYear groupe la même liste par année calendaire, avec les années décroissantes et les pages au sein de chaque année toujours plus récent d’abord :

Utile pour les pages d’archive chronologiques (<h2>2024</h2> puis une liste).

.site.authorRegistry

La table [[authors]] brute de site.toml, préservée dans l’ordre de déclaration. Chaque entrée est la table TOML telle quelle — id, name, role, bio, avatar, email, plus tout champ personnalisé que vous avez ajouté.

Distincte de .site.authors, qui est filtrée aux auteurs ayant au moins une page qui les référence et est augmentée de count, url et pages. Utilisez .site.authorRegistry pour les layouts d’annuaire du personnel qui devraient montrer chaque membre de l’équipe peu importe combien de sermons ou d’articles ils ont rédigés ; utilisez .site.authors pour les archives « parcourir par auteur ».

Quand /authors/ et /authors/<id>/ sont rendues

Les deux layouts ont des conditions différentes pour que les thèmes puissent livrer une « page d’équipe » montrant tout le monde, même sur un site neuf sans articles :

• layouts/_default/author-list.html → /authors/index.html est rendue dès qu’un registre existe tout court ([[authors]] non vide dans site.toml). Le layout itère typiquement .site.authorRegistry.
• layouts/_default/author-page.html → /authors/<id>/index.html n’est rendue que pour les auteurs ayant au moins une page qui les référence. Une page d’archive par auteur vide serait trompeuse.

L’un ou l’autre layout est optionnel — l’absence du fichier signifie que la sortie correspondante est silencieusement sautée.

Renommer le préfixe d’URL — authorsPath

Par défaut, le listing d’équipe et les archives par auteur résident tous deux sous /authors/. Les sites utilisant un thème non orienté blogue veulent souvent un libellé différent — un café veut /team/, un site de documentation veut /people/. Définissez authorsPath dans site.toml :

authorsPath = "/team/"

Le moteur pivote trois choses de concert : le répertoire de sortie sur le disque, le champ url de chaque terme .site.authors, et la chaîne .site.authorsPath faite remonter aux gabarits. Les thèmes devraient lire {{ .site.authorsPath }} plutôt que de coder en dur /authors/ pour qu’une surcharge au niveau du site se propage sans édition de layout.

Normalisation indulgente : team, /team, team/ et /team/ deviennent tous /team/. Les segments de traversée de chemin (., ..) sont rejetés avec un avertissement et le défaut est utilisé.

.site.now

Horodatage du moment de la construction capturé une fois par construction, en quatre formes pour que la bonne soit toujours sous la main :

Le modèle de site statique signifie que « maintenant » est légitimement figé au moment de la construction. Le rechargement à chaud relance la construction à chaque changement, donc la valeur reste fraîche pendant l’aperçu local.

.site.events

Pages dans la section d’événements configurée (eventsSection dans site.toml, par défaut "events") avec un frontmatter date: explicite, triées croissant. Chaque entrée est en forme d’enregistrement .site.pages — title, url, date, dateShort, summary, plus tout frontmatter que la page d’événement déclare (eventTime, eventLocation, recurring, etc.).

Inclut les événements datés dans le futur : les événements sont annoncés avant qu’ils n’arrivent, et le filtre des articles futurs à l’échelle du site est exempté pour les pages de la section d’événements pour que les entrées .site.events et les pages de détail d’événement correspondantes survivent à la construction. Les articles datés dans le futur (tout ce qui est hors de la section d’événements) continuent d’être sautés comme futurs — voir l’option CLI --future pour supplanter par construction.

Les événements récurrents apparaissent une fois chacun (l’enregistrement de page canonique) ; utilisez .site.calendar pour le déploiement occurrence par occurrence.

.site.calendar

N mois pré-calculés (par défaut 12, supplantez via calendarMonths dans site.toml) en commençant au mois courant. Chaque mois est :

Chaque cellule :

Les événements hebdomadaires récurrents (recurring: weekly + recurringDay: optionnel) sont déployés sur chaque jour de semaine correspondant depuis leur date de début vers l’avant. Un événement récurrent sans recurringDay: retombe sur le jour de la semaine de sa date de début. Les événements non récurrents apparaissent une fois sur leur date.

La grille est toujours 6×7 = 42 cellules par mois pour que les gabarits de calendrier n’aient pas à traiter spécialement les limites de mois ; les cellules hors-mois se rendent comme remplissage day=null.

.site.photos

Entrées de frontmatter photos: agrégées depuis chaque page du site, triées par la date de la page parente décroissante. Chaque entrée :

Forme du frontmatter — soit une liste de chaînes (URL seulement), soit une liste de cartes avec les clés src / caption / alt :

photos:
  - "/img/picnic-01.jpg"
  - { src: "/img/picnic-02.jpg", caption: "The pie table" }

Les pages sans frontmatter photos: ne contribuent rien.

.site.data

Données structurées que le thème ou l’auteur du site veut que les gabarits puissent atteindre sans les forcer dans le frontmatter de chaque page. juicer balaie le dataDir (par défaut data/) sous la racine du site et sous chaque thème actif :

data/team.toml              → .site.data.team
data/menu/lunch.yaml        → .site.data.menu.lunch
data/menu/dinner.toml       → .site.data.menu.dinner

Le nom de base du fichier (sans extension) devient la clé feuille ; chaque répertoire sous data/ devient un niveau d’imbrication. Les .toml et les .yaml / .yml sont tous deux acceptés — choisissez la forme qui convient le mieux aux données. Le JSON n’est pas analysé nativement, mais comme c’est un strict sous-ensemble de YAML, vous pouvez renommer .json → .yaml et ça fonctionne.

Un usage typique :

# data/team.toml# data/team.toml
[[members]]
name = "Alice"
role = "Lead"

[[members]]
name = "Bob"
role = "Eng"

{{ for m <- .site.data.team.members }}
  <li>{{ m.name }} — {{ m.role }}</li>
{{ end }}

Superposition de thème. Les thèmes peuvent livrer leur propre répertoire data/ ; les entrées du site l’emportent à la granularité du fichier feuille. Si un thème fournit data/site.toml et que le site fournit data/site.toml, le fichier du site remplace celui du thème au chemin de clé .site.data.site. Le site ne fusionne pas en profondeur les champs — pour prendre en charge les surcharges partielles en tant qu’auteur de thème, isolez dans un sous-répertoire (data/colors/default.toml + data/colors/dark.toml).

Notes de format. Le TOML à la racine d’un fichier s’analyse toujours en une carte ; le YAML peut s’analyser en une liste (data/sponsors.yaml commençant par - name: ...) ou un scalaire, mais une carte est de loin la forme la plus utile car l’accès aux champs imbriqués (.site.data.sponsors[0].name) est plus lisible que l’indexation positionnelle dans la plupart des gabarits.

.site.comments

Une transmission de la table [comments] de site.toml (voir Config → [comments]). juicer ne livre jamais de backend de commentaires — le bloc de configuration est opaque pour le moteur, et les partials de thème sont responsables de le lire et d’émettre le HTML d’intégration.

provider est la seule convention ; tout le reste est propre au fournisseur et défini par le thème. Un thème qui prend en charge plusieurs fournisseurs s’embranche typiquement dessus :

{{ if .site.comments }}
  {{ if eq .site.comments.provider 'giscus' }}
    {{ partial 'comments/giscus.html' . }}
  {{ end }}
  {{ if eq .site.comments.provider 'utterances' }}
    {{ partial 'comments/utterances.html' . }}
  {{ end }}
  {{ if eq .site.comments.provider 'disqus' }}
    {{ partial 'comments/disqus.html' . }}
  {{ end }}
{{ end }}

Le {{ if .site.comments }} externe est la bonne condition pour « commentaires activés ou désactivés à l’échelle du site » — quand aucune table [comments] n’est définie dans site.toml, .site.comments est absent et la condition s’évalue à faux. Les thèmes qui permettent le renoncement par page vérifient aussi {{ if .page.comments }} (ou similaire) pour que des articles individuels puissent supplanter le réglage du site.

Pages d’alias

Le frontmatter aliases: [...] fait émettre à juicer une page de redirection à chaque URL listée. Le layout d’alias (ou le repli intégré) voit un contexte de données distinct :

Si layouts/_default/alias.html existe, il est rendu avec les données ci-dessus. Sinon juicer écrit une page HTML intégrée minimale avec un <meta http-equiv="refresh"> vers .target.

.page

L’enregistrement enrichi de la page courante :

Forme de .page.series

Définie quand la page déclare series: dans le frontmatter :

Ordonnancement : seriesOrder explicite croissant d’abord, puis .page.date croissant, puis le nom de fichier comme départage stable.

Pour les pages d’index de section (où .page.isSection vaut true), en plus :

Forme de .page.backlinks

Une liste d’enregistrements minces — un par page contenant un lien interne pointant vers le permalien de la page courante. Triés par titre du référent pour un rendu déterministe.

Les gabarits qui ont besoin d’un enregistrement de référent plus riche (mots-clés, date, auteur, etc.) le recherchent via .site.pagesByPath[bl.url] — garder les enregistrements intégrés minces évite les cycles quand deux pages se lient l’une l’autre.

L’index inversé est construit pendant la passe markdown à partir des destinations de lien de l’AST de chaque page. Filtrés au moment de la collecte : les URL absolues (https://…, mailto:, tel:), les ancres à fragment seul (#section), et les auto-liens. Les chaînes de requête et les fragments sont retirés avant la correspondance, donc [X](/target/#section) et [X](/target/?q=1) comptent tous deux comme un lien vers /target/. Les listes, tableaux, listes de définitions, définitions de notes de bas de page, citations et éléments de liste sont tous parcourus — partout où un auteur peut déposer un [text](url) en markdown, ça compte.

Pied de page « Lié depuis » de style wiki dans un layout :

{{ if .page.backlinks }}
  <aside class="backlinks">
    <h2>Linked from</h2>
    <ul>
      {{ for bl <- .page.backlinks }}
        <li><a href="{{ bl.url }}">{{ bl.title }}</a>{{ if bl.summary }} — {{ bl.summary }}{{ end }}</li>
      {{ end }}
    </ul>
  </aside>
{{ end }}

.section

Toujours disponible (pour les pages non-_index, elle décrit la section englobante) :

.section.paginator

Les pages d’index de section se rendent une fois par tranche quand paginate est défini. Les pages non-section obtiennent un paginateur avec total = 1 pour que le même gabarit puisse le lire sans condition.

La tranche 2+ réside à <section>/page/<N>/index.html — des URL de style répertoire qui fonctionnent sur n’importe quel hôte statique sans règles de réécriture.

Paquets de page

Un paquet de page est un répertoire de contenu dont les fichiers non-markdown (images, pièces jointes, tout ce qui n’est pas .md / .toml / .yaml / .yml / .html / .sq) sont co-localisés avec la page et sont copiés vers l’URL de sortie de la section.

Déposez les ressources à côté du markdown :

content/iceland-2024/
  _index.md
  hero.jpg
  skogafoss.jpg
  notes.md

Au moment de la construction, juicer copie les ressources vers le répertoire de sortie de la section et les expose sur l’enregistrement de page :

• hero.jpg → dst/html/iceland-2024/hero.jpg → URL /iceland-2024/hero.jpg.
• {{ .page.assets }} sur l’index de section OU sur notes.md est la même liste — les ressources sont par répertoire, pas par page. .section.assets est un alias pour les gabarits qui préfèrent les lire depuis la section.

Chaque enregistrement de ressource :

Itérez dans un layout pour rendre une galerie, une liste de pièces jointes, etc. :

{{ if .page.assets }}
  <ul class="bundle-files">
    {{ for a <- .page.assets }}
      <li><a href="{{ a.url }}">{{ a.name }}</a></li>
    {{ end }}
  </ul>
{{ end }}

Chemins d’image relatifs au paquet

À l’intérieur d’un paquet, imageVariants, srcset et imageDims résolvent les chemins nus (sans / de tête) contre le paquet source de la page avant de retomber sur static/. Cela signifie qu’une image de héros réside à la page et que le gabarit n’a pas besoin de savoir où :

{{ with vs = imageVariants 'hero.jpg' }}
  <picture>
    <source type="image/webp" srcset="{{ srcset 'hero.jpg' 'webp' }}">
    <img src="{{ vs.original }}" width="{{ vs.originalWidth }}" height="{{ vs.originalHeight }}" alt="">
  </picture>
{{ end }}

Déplacez le paquet vers une URL différente, le layout fonctionne toujours. Les chemins absolus (/static/hero.jpg) continuent de se résoudre depuis la racine source — la préférence de paquet ne s’active que pour les chemins nus.

Quand NE PAS utiliser un paquet

• Habillage à l’échelle du site (logo, favicon, polices) : gardez-les dans static/ pour que chaque page puisse les atteindre via une URL absolue.
• Ressources partagées utilisées depuis de nombreuses pages : pareil — les paquets sont pour les fichiers propres à une page. Mettre un logo dans chaque paquet dupliquerait des octets et casserait un changement de logo.
• Fichiers dans un répertoire sans contenu markdown. Les paquets ont besoin d’une page pour les ancrer ; les ressources orphelines sont silencieusement sautées.

builtin asset

La fonction de gabarit asset résout un nom logique en l’URL de sa sortie compilée (et éventuellement avec empreinte). Le manifeste vient du pipeline [assets].

<link rel="stylesheet" href="{{ asset 'site.css' }}">
<script src="{{ asset 'main.js' }}" defer></script>

La règle « entrée inchangée en cas d’absence » est délibérée : l’effet d’une faute de frappe apparaît dans le HTML rendu plutôt que de disparaître dans une chaîne vide, ce qui est plus rapide à repérer dans une sortie de construction ou un panneau d’outils de développement du navigateur.

Clés d’habillage à l’échelle du site

Les clés de premier niveau de site.toml que les thèmes fournis lisent depuis .site.* pour piloter l’habillage partagé — favicon, attribution de pied de page, lien de dépôt, feuilles de style personnalisées — sont cataloguées dans Thématisation avec les tables de palette / typographie / dimensionnement [juicerXxx] par thème.

Autres clés de premier niveau

Ordonnancement des pages

pageOrder est poids croissant, puis nom croissant. Les pages sans frontmatter weight se trient après les pages pondérées mais avant toute valeur sentinelle.