Un gabarit ne va jamais rien chercher. On lui remet un ensemble de valeurs prêtes à l’emploi — FolioPress l’appelle le contexte — et il affiche ce dont il a besoin. Une partie de l’ensemble est identique sur chaque page ; le reste dépend du gabarit en cours de rendu.
Commun à tous les gabarits
Variable Ce que c’est
page La page ou l’article consulté, déjà dans la langue courante (voir plus bas). None sur l’archive d’étiquette et la recherche.
site_title, site_description, footer Issus des Réglages du site, dans la langue courante. footer est déjà rendu depuis Markdown.
navigation_menu Le menu configuré dans l’administration : une liste de {title, url, slug, page_id}, chaque url prête à l’emploi dans cette langue.
languages Les langues du site, indexées par code. Chaque entrée : code, name, native_name, short_code, menu_label, flag.
current_language, current_language_code, default_language_code La langue en cours de rendu (même forme qu’une entrée de languages), son code, et la langue principale du site.
language_switch_urls Indexé par code de langue : l’URL de cette même page dans cette langue, slug traduit compris.
home_url, url_language_code La page d’accueil dans la langue courante (/ ou /pt-pt), et le préfixe en minuscules à placer devant toute URL que vous construisez vous-même ('' pour la langue principale).
static_url, media_url D’où sont servis les fichiers de ce thème (/static/<thème>) et où vivent les images téléversées.
page_title, meta_description, canonical_url, hreflang_urls, social_image_url, twitter_card_type, json_ld Tout ce dont le <head> a besoin : un titre d’onglet sensé, des URL canonique et alternatives par langue absolues, une image Open Graph et des données structurées — le tout précalculé.
theme_name, theme_info, theme_settings Le nom du thème actif, son theme.yml complet et son bloc settings.
t Le traducteur du thème lui-même : {{ t('Read more') }} cherche la phrase dans locales/<langue>.json (voir plus bas).
request La requête FastAPI, pour le rare cas où vous avez besoin du chemin ou d’un paramètre.
L’objet page
La même forme, qu’il s’agisse d’une page, d’un article ou d’un élément de n’importe quelle liste d’articles :
Champ Notes
title, slug, url Dans la langue courante. url est complète, préfixe de langue ou domaine propre à la langue compris.
content Déjà converti de Markdown en HTML — affichez-le avec {{ page.content | safe }}.
excerpt, meta_description Les formes courtes, dans la langue courante.
poster_image_url L’URL complète de l’image de couverture, ou None.
gallery, content_gallery Des listes d’images : {id, url, title, width, height, original_filename}. Utilisez image.url directement.
tags {slug, title, url} pour chaque étiquette publique. Les étiquettes privées ne sont jamais incluses.
is_post, is_featured, published_at, created_at, updated_at S’il s’agit d’un article, s’il est mis en avant, et ses dates.
id L’identifiant en base — pratique pour les ancres et les clés de cache.
Listes d’articles
Gabarit Variable Contenu
home.html posts (alias recent_posts), pages, is_home Les articles partageant une étiquette avec la page d’accueil, en nombre et ordre définis par la section home de theme.yml. Une page d’accueil sans étiquette ne reçoit aucun article — étiquetez-la pour la remplir.
page.html posts (alias page_posts) Les articles partageant une étiquette avec cette page, selon la section page. C’est ainsi qu’une page « Blog » liste ses articles.
post.html related_posts, is_post Les autres articles partageant une étiquette avec celui-ci, selon la section post.
tag.html tag (title, slug), posts Tous les articles publiés portant cette étiquette, selon la section tag.
search.html search_query, search_results, results_count Le terme saisi et les pages et articles correspondants.
Chaque liste d’articles est accompagnée d’une pagination de même forme : has_pagination, current_page, total_pages, has_previous, has_next, previous_page, next_page, et pagination_urls avec first, previous, next et last — None là où il n’y a nulle part où aller. Avec has_pagination désactivé dans theme.yml, la liste est simplement coupée à posts et les indicateurs restent à faux.
Les langues et le sélecteur
Deux des champs de langue sont calculés pour vous. short_code est le code de langue seul — EN — sauf si le site active aussi une autre variante de la même langue, auquel cas il garde sa région : EN-US et EN-GB. menu_label suit la même règle avec les noms : English, ou English (US) et English (UK). C’est exactement la règle qu’utilise le sélecteur de langue de l’administration elle-même, si bien que le site et l’administration ne se contredisent jamais sur un libellé. Un sélecteur complet est donc court :
{% if languages | length > 1 %} <button type="button" aria-label="{{ t('Change language') }}"> {{ current_language.short_code }} </button> <ul> {% for lang in languages.values() | sort(attribute='menu_label') %} <li> {% if lang.code == current_language.code %} <span aria-current="true">{{ lang.menu_label }}</span> {% else %} <a href="{{ language_switch_urls[lang.code] }}" hreflang="{{ lang.code }}">{{ lang.menu_label }}</a> {% endif %} </li> {% endfor %} </ul> {% endif %}
language_switch_urls pointe déjà vers la même page dans chaque langue — le slug traduit, ou la page d’accueil si cette traduction n’existe pas encore —, de sorte qu’un sélecteur ne construit jamais d’URL lui-même.