Référence : thèmes de site (plugin web)¶
Cette page décrit, de façon exhaustive et neutre, le thème d'un site du plugin web : sa composition, le catalogue fourni, la bibliothèque de thèmes personnels et ses routes, le contrat d'écriture de ses gabarits, les classes CSS que le site produit, les limites du CSS d'un thème et les règles de résolution d'un thème vers un site.
Pour appliquer un thème depuis l'interface, voir le guide Choisir l'apparence de son site ; pour en écrire un, Créer, dupliquer, modifier et supprimer un thème de site. Pour le pourquoi du modèle, voir Modèle de thème et catalogue fourni et Écrire ses propres thèmes : les arbitrages.
Composition d'un thème¶
Un thème est fait de quatre sources, et de rien d'autre :
| Source | Nature | Rôle |
|---|---|---|
headerHtml |
Gabarit Twig sandboxé | Contenu de l'en-tête du site |
bodyHtml |
Gabarit Twig sandboxé | Corps de page, contenant l'emplacement du contenu (content) |
footerHtml |
Gabarit Twig sandboxé | Contenu du pied de page |
css |
Feuille de style | Habillage complet du site |
Ces quatre sources, le nom affiché, la clé et le drapeau builtin sont portés par le DTO ThemeSource (src/Plugin/Web/src/Theme/ThemeSource.php). C'est la seule forme manipulée par le rendu, par le contrôleur de feuille de style et par le sélecteur de l'onglet Apparence : l'origine du thème (fichier ou base) n'est visible nulle part ailleurs.
Il n'existe aucun HTML ni CSS attaché au site lui-même : le site ne porte que la clé du thème appliqué (Site::themeKey, src/Plugin/Web/src/Entity/Site.php).
Le catalogue fourni¶
Trois thèmes sont livrés avec la plateforme. Ils ne sont ni modifiables ni supprimables : ils vivent en fichiers versionnés dans le dépôt et il n'existe aucun chemin d'écriture vers eux.
| Clé | Nom affiché | Esprit |
|---|---|---|
default |
Par défaut | La ligne éditoriale de Kirexo : colonne de lecture étroite, marque à gauche et navigation à droite, cartes d'articles séparées par un filet. |
classic |
Classique | La mise en page d'un quotidien : bandeau de titre centré entre deux filets, devise, navigation en petites capitales, titres serif, chapôs gris. |
minimal |
Minimal | L'esprit du smolweb : police système, colonne d'environ 40 rem, liens soulignés, ni ombre ni arrondi, quelques dizaines de lignes de CSS. |
Chaque thème fourni occupe un répertoire src/Plugin/Web/themes/<clé>/ contenant cinq fichiers :
| Fichier | Contenu |
|---|---|
theme.json |
Objet JSON déclarant au moins la clé name (nom affiché). |
header.html.twig |
Gabarit de l'en-tête. |
body.html.twig |
Gabarit du corps. |
footer.html.twig |
Gabarit du pied de page. |
theme.css |
Feuille de style du thème. |
La lecture est faite par BuiltinThemeCatalog (src/Plugin/Web/src/Theme/BuiltinThemeCatalog.php), qui expose le catalogue dans l'ordre stable default, classic, minimal. Un fichier manquant ou illisible, ou un theme.json sans clé name de type chaîne, lève une \RuntimeException : c'est une erreur de packaging, pas une entrée utilisateur.
Seule opération offerte sur un thème fourni : la duplication, qui en produit une copie éditable appartenant à l'utilisateur. Voir Thèmes personnels.
Thèmes personnels¶
Un utilisateur possède une bibliothèque de thèmes, de portée compte : un thème lui appartient et est applicable au site de n'importe lequel de ses carnets. Ces thèmes sont des entités (Theme, src/Plugin/Web/src/Entity/Theme.php, table web_plugin_theme) portant les quatre mêmes sources qu'un thème fourni, plus un nom, un propriétaire (userId, référence faible vers App\Entity\User) et des horodatages createdAt / updatedAt.
La clé d'un thème personnel dans Site::themeKey et dans les routes est son identifiant UUIDv7.
Points d'accès¶
| Élément | Valeur |
|---|---|
| Bibliothèque | /u/web/themes |
| Entrées dans l'interface | Menu du compte de l'espace utilisateur : entrée « Mes thèmes ». Plus, pour un carnet dont le site existe, l'onglet Apparence de son hub de réglages : lien « Mes thèmes » dans le texte d'aide et bouton « Gérer mes thèmes » sous le formulaire |
| Prérequis d'accès | Être authentifié·e (ROLE_USER) et avoir le plugin web activé ; tout /u/web/… répond 404 sinon (WebSettingsAccessSubscriber, src/Plugin/Web/src/EventSubscriber/WebSettingsAccessSubscriber.php) |
L'entrée de menu vient du plugin, pas du cœur¶
L'entrée « Mes thèmes » du menu du compte n'est écrite nulle part dans le cœur. Elle est contribuée par le plugin web, qui implémente la capability UserMenuContributorInterface (src/Plugin/Web/src/WebDiffusionPlugin.php) : userMenuLabel() rend 'Mes thèmes', userMenuRouteName() rend 'web_plugin_theme_index'.
Le composant App\Twig\Components\UserMenuPluginLinks (src/Twig/Components/UserMenuPluginLinks.php) parcourt le registre au rendu et retient un plugin à deux conditions cumulatives :
| Condition | Mécanisme |
|---|---|
| Le plugin déclare la capability | instanceof UserMenuContributorInterface |
| Le plugin est actif pour le compte connecté | PluginStateResolverInterface::resolve($key, $user) puis PluginState::isActive() |
Le rendu lui-même est fait par <twig:UserMenuPluginLinks /> dans templates/components/Header.html.twig, uniquement pour space == 'user'. Détail du contrat : Référence : contrat de plugin — UserMenuContributorInterface ; place de l'entrée dans le menu : Header et menu utilisateur.
La bibliothèque est joignable sans carnet ni domaine
C'est la raison d'être de cette entrée, et la raison pour laquelle userMenuRouteName() ne prend aucun paramètre : l'écran est de portée compte, pas de portée carnet ni site. Un utilisateur qui vient d'activer le plugin web, sans aucun carnet et sans aucun domaine rattaché, atteint donc /u/web/themes depuis le menu de son espace.
Les deux entrées de l'onglet Apparence restent des raccourcis contextuels : elles n'existent que pour un carnet dont le site existe (domaine rattaché), puisque cet onglet n'apparaît qu'à ce moment-là. Elles ne sont pas le seul chemin.
L'entrée ne peut pas mener à un 404
La condition qui fait apparaître l'entrée et celle qui laisse passer la requête ne sont pas seulement voisines : c'est la même expression. WebSettingsAccessSubscriber rend 404 sur tout /u/web/… quand PluginActivationCheckerInterface::isEnabledFor() est faux, et l'implémentation cœur de ce contrat (src/Service/Plugin/PluginActivationChecker.php) se réduit à resolve($pluginKey, $user)->isActive() — exactement ce que teste UserMenuPluginLinks.
Une fonctionnalité inaccessible n'est donc jamais révélée dans le menu, et une entrée visible mène toujours à une page servie. Les deux points ne peuvent pas diverger sans qu'on change le résolveur, qui est leur source commune.
Routes¶
Toutes les routes ci-dessous vivent sous /u/web/themes. Chaque POST exige un jeton CSRF lié à la ressource.
| Méthode | Chemin | Nom | Jeton CSRF | Contrôle d'accès |
|---|---|---|---|---|
| GET | /u/web/themes |
web_plugin_theme_index |
— | ROLE_USER |
| GET | /u/web/themes/nouveau |
web_plugin_theme_new |
— | ROLE_USER |
| POST | /u/web/themes |
web_plugin_theme_create |
theme_create |
ROLE_USER |
| POST | /u/web/themes/{key}/dupliquer |
web_plugin_theme_duplicate |
theme_duplicate-<key> |
ROLE_USER + appartenance du thème source |
| GET | /u/web/themes/{id}/edition |
web_plugin_theme_edit |
— | THEME_EDIT |
| POST | /u/web/themes/{id} |
web_plugin_theme_update |
theme_update-<id> |
THEME_EDIT |
| POST | /u/web/themes/{id}/supprimer |
web_plugin_theme_delete |
theme_delete-<id> |
THEME_DELETE |
{id} est contraint à Requirement::UUID_V7 et résolu par MapEntity : un identifiant inconnu donne 404. {key} de la duplication accepte la clé d'un thème fourni ou l'identifiant d'un thème personnel ([A-Za-z0-9-]{1,50}).
Contrôleurs : src/Plugin/Web/src/Controller/WebPluginThemeIndexController.php et ses homologues …New…, …Create…, …Duplicate…, …Edit…, …Update…, …Delete….
Autorisations¶
ThemeVoter (src/Plugin/Web/src/Security/ThemeVoter.php) expose deux attributs, THEME_EDIT et THEME_DELETE, accordés au seul propriétaire du thème (comparaison de Theme::userId avec l'identifiant du compte connecté). Le thème d'un autre compte donne 403 en modification comme en suppression.
Les thèmes fournis ne passent pas par ce Voter : ce ne sont pas des entités et aucune route n'écrit dans src/Plugin/Web/themes/.
La bibliothèque¶
web_plugin_theme_index affiche deux listes : les thèmes fournis (badge « Fourni », action Dupliquer) puis les thèmes de l'utilisateur (Modifier, Dupliquer, Supprimer). Les choix proviennent de ThemeResolver::choicesFor() — les trois fournis, puis les thèmes du compte triés par nom.
Chaque ligne affiche le nombre de sites de ce compte servis par ce thème, obtenu en une requête agrégée (SiteRepositoryInterface::countByThemeKeys(), src/Plugin/Web/src/Repository/SiteRepositoryInterface.php). Le compte est scopé à l'utilisateur : les clés des thèmes fournis étant partagées par toute la plateforme, un décompte global divulguerait l'usage des autres comptes.
Création¶
web_plugin_theme_new ne demande que le nom. web_plugin_theme_create crée le thème comme une copie du thème fourni « Par défaut » (ThemeResolver::defaultTheme()) : les quatre sources sont recopiées, puis l'utilisateur est redirigé vers l'écran de modification.
| Situation | Effet |
|---|---|
| Nom valide | Thème créé, message « Thème créé à partir de « Par défaut ». À vous de l'écrire. », redirection vers web_plugin_theme_edit |
| Nom invalide | Message d'erreur, redirection vers web_plugin_theme_new |
| Jeton CSRF invalide | 403 |
Duplication¶
web_plugin_theme_duplicate copie les quatre sources d'un thème — fourni ou personnel — dans un thème neuf appartenant à l'utilisateur, nommé <nom d'origine> (copie) (tronqué pour tenir dans 80 caractères), puis redirige vers son écran de modification avec le message « « nom » dupliqué. ».
Le thème source est cherché parmi les choix réels du compte : une clé inconnue ou un thème d'un autre compte produit le message « Ce thème n'existe pas ou ne vous appartient pas. » et une redirection vers la bibliothèque.
La copie d'un thème fourni rend à l'identique de l'original : c'est l'invariant « aucune déclaration d'un thème fourni n'est retirée par le filtre » qui le garantit.
Modification¶
L'écran web_plugin_theme_edit porte un seul formulaire vers web_plugin_theme_update, avec cinq champs :
| Champ | Contenu |
|---|---|
name |
Nom affiché |
headerHtml |
Gabarit de l'en-tête |
bodyHtml |
Gabarit du corps |
footerHtml |
Gabarit du pied de page |
css |
Feuille de style |
La saisie est portée par le DTO ThemeForm (src/Plugin/Web/src/Dto/ThemeForm.php). Le nom est trimé ; un champ de zone absent ou non scalaire vaut chaîne vide.
Validation¶
| Règle | Message |
|---|---|
name non vide |
« Donnez un nom à votre thème. » |
name ≤ 80 caractères |
« Le nom d'un thème ne dépasse pas 80 caractères. » |
| Chaque zone ≤ 500 000 caractères | « L'en-tête dépasse la taille maximale (500000 caractères). » (idem corps, pied de page, CSS) |
Cette borne de 500 000 caractères est alignée sur le max_input_length du profil sanitizer site_public : au-delà, le rendu public tronquerait silencieusement.
Aucune autre règle ne bloque l'enregistrement. En particulier, un corps sans emplacement de contenu, une balise refusée par le sanitizer ou un tag Twig hors sandbox n'empêchent pas d'enregistrer : ils produisent des diagnostics.
En cas de violation, le formulaire est réaffiché avec la saisie (réponse 422 Unprocessable Content), sans redirection : les quatre zones ne sont pas perdues.
Persistance¶
| Source | Régime |
|---|---|
css |
Persisté déjà filtré par CssFilter — la saisie brute n'est jamais stockée |
headerHtml, bodyHtml, footerHtml |
Persistés bruts, assainis au rendu (sandbox + sanitizer), comme les thèmes fournis |
L'enregistrement appelle aussi Theme::touch() (mise à jour de updatedAt).
Diagnostics rendus après enregistrement¶
| Origine | Forme du message |
|---|---|
| Filtre CSS | <raison> — <fragment>, une entrée par retrait (raisons : règle @ interdite, propriété non autorisée, URL non autorisée, motif interdit, déclaration invalide) |
| Zones HTML | <zone> : Des balises HTML non autorisées ont été retirées par le filtre de sécurité. |
| Zones HTML (sandbox) | <zone> : Le tag « … » n'est pas autorisé., … Le filtre « … » n'est pas autorisé., … La fonction « … » n'est pas autorisée., … Erreur de syntaxe Twig : … |
| Corps sans emplacement | « Corps : le contenu n'est placé nulle part. Ajoutez {{ content }} à l'endroit où vos articles doivent apparaître — sans lui, ils sont ajoutés à la fin. » |
<zone> vaut En-tête, Corps ou Pied de page. Une zone vide n'est pas analysée.
Les zones sont éprouvées par HtmlOverrideRenderer::renderWithReport() sur un contexte d'exemple peuplé (un article, une page, un profil), afin que les conditions et les boucles du gabarit s'exécutent réellement. Un retrait HTML n'est signalé que si le nombre de balises diminue : le rendu public reposant toujours rel sur tout <a> (voir L'attribut rel des liens), une comparaison de chaînes se déclencherait sur n'importe quel lien.
Message de succès : « Thème enregistré. »
Suppression¶
web_plugin_theme_delete supprime le thème même s'il est en service. Les sites du compte qui portaient sa clé retombent sur « Par défaut » par la règle de résolution, et leur cache est invalidé.
| Situation | Message |
|---|---|
| Aucun site concerné | « « nom » supprimé. » |
| N sites concernés | « « nom » supprimé. N site(s) sont repassés au thème « Par défaut ». » |
La confirmation affichée avant l'envoi est un comportement client (contrôleur Stimulus confirm) ; sans JavaScript, le formulaire est posté directement et le jeton CSRF reste la garde.
Effet sur les sites¶
Enregistrer ou supprimer un thème invalide le cache de tous les sites du compte qui l'appliquent (SiteCacheInterface::invalidateSite()). Le rechargement suivant sert les pages avec l'état à jour.
La feuille de style publique est référencée avec un paramètre v — une empreinte courte du CSS servi, calculée par SiteRenderer — de sorte que l'URL change exactement quand le style change et qu'aucun cache navigateur ne serve l'ancienne feuille.
L'éditeur de CSS assisté¶
Le champ CSS est rendu par le Live Component ThemeCssEditor (src/Plugin/Web/src/Twig/Component/ThemeCssEditor.php), monté à l'intérieur du formulaire du thème dont il partage le bouton d'enregistrement.
| Élément | Comportement |
|---|---|
Action validate (« Vérifier le CSS ») |
Filtre le CSS courant et affiche les retraits, sans rien persister |
| Aucun retrait | « Aucun fragment ne sera retiré. » |
| Retraits | Liste <fragment> — <raison>, sous « Ces fragments seront retirés à l'enregistrement, pour votre sécurité : » |
| Autocomplétion | Restreinte à CapabilityWhitelist::allowedCssProperties(), sérialisée par le serveur — aucune liste de propriétés n'est dupliquée côté JavaScript |
| Sans JavaScript | Le <textarea name="css"> part avec le formulaire ; seules la coloration, l'autocomplétion et l'action « Vérifier » disparaissent |
Le panneau d'aide « Ce que vous pouvez écrire » (composant CapabilityPanel, src/Plugin/Web/src/Twig/Component/CapabilityPanel.php) est présent sur le même écran, en disclosure. Son contenu est généré depuis la whitelist serveur, jamais recopié.
L'attribut rel des liens écrits dans un gabarit de thème suit une règle propre au rendu public, décrite en L'attribut rel des liens.
Où le thème s'applique¶
Le rendu d'une page publique est assemblé par SiteRenderer (src/Plugin/Web/src/Service/SiteRenderer.php) et posé par le gabarit src/Plugin/Web/templates/site/layout.html.twig :
| Zone du thème | Emplacement dans la page |
|---|---|
headerHtml |
à l'intérieur de <header class="site-header"> |
bodyHtml |
à l'intérieur de <main id="main" class="site-main"> |
footerHtml |
à l'intérieur de <footer class="site-footer"> |
css |
feuille externe text/css, chargée après le socle du design system |
Le <body> de la page porte la classe site-theme--<clé> : point d'accroche stable, sans effet de style par lui-même.
La feuille du thème est servie par deux routes, selon le contexte :
| Route | Chemin | Contexte |
|---|---|---|
web_plugin_public_stylesheet |
GET /site.css |
Site public (route conditionnée à un hôte de site) |
web_plugin_site_theme_stylesheet |
GET /u/web/reglages/site/{notebookId}/theme.css |
Espace utilisateur, pour l'aperçu d'article |
Contrôleurs : src/Plugin/Web/src/Controller/WebPluginPublicStylesheetController.php et src/Plugin/Web/src/Controller/WebPluginSiteThemeStylesheetController.php. Les deux servent la même feuille : l'aperçu d'article (/u/web/articles/{id}/apercu) montre l'article dans le thème réellement appliqué au site.
La page publique référence la feuille avec un paramètre de version, /site.css?v=<empreinte> : une empreinte courte du CSS du thème résolu, calculée par SiteRenderer (src/Plugin/Web/src/Service/SiteRenderer.php). L'URL change donc exactement quand le style change. La réponse porte par ailleurs un ETag dérivé du contenu servi et un max-age de 300 secondes.
Contrat des gabarits de thème¶
Les trois gabarits sont rendus dans une sandbox Twig isolée (HtmlOverrideRenderer, src/Plugin/Web/src/Security/HtmlOverrideRenderer.php), puis assainis par le sanitizer site_public. Les capacités sont déclarées par CapabilityWhitelist (src/Plugin/Web/src/Security/CapabilityWhitelist.php), source unique de vérité.
Variables disponibles¶
| Variable | Contenu |
|---|---|
articles |
Teasers des articles de la page courante. Chaque entrée : title, slug, excerpt, publishedAt (date ISO 8601), url. |
pages |
Pages spéciales publiées du menu, dans l'ordre du menu. Chaque entrée : title, slug, url. |
profile |
Profil du site : title, description, themeKey, homeUrl, currentUrl. |
content |
Emplacement du contenu de la page — voir ci-dessous. |
currentUrl est l'URL canonique de la page rendue : elle permet de marquer l'entrée courante du menu (aria-current="page"), comme le font les trois thèmes fournis.
articles n'est peuplé que sur la page d'accueil
Le contexte est bâti uniquement à partir des données déjà chargées pour la page servie, sans requête supplémentaire. Sur une page d'article, une page spéciale ou un aperçu, articles vaut [] — une boucle for sur cette variable n'y affiche rien. pages et profile sont peuplés partout.
Aucune entité n'entre dans la sandbox : le contexte ne transporte que des scalaires et des tableaux de scalaires (SiteRenderContext, src/Plugin/Web/src/Security/SiteRenderContext.php).
Syntaxe autorisée¶
| Catégorie | Autorisé |
|---|---|
| Tags | if, for, set, apply — et rien d'autre. Ni include, ni extends, ni embed, ni use, ni import, ni macro. |
| Fonctions | Aucune. include(), path(), url(), attribute(), constant(), dump(), source() n'existent pas dans la sandbox. |
| Filtres | Un jeu restreint de filtres de présentation (échappement, casse, trim, length, default, join, nl2br, striptags, slice, first, last, date, format). Pas de raw : l'auto-échappement n'est pas contournable. |
| Tests | defined, empty, null, even, odd, same as. |
| Méthodes et propriétés d'objet | Aucune. |
Les listes exhaustives de tags HTML, d'attributs, de filtres et de tests sont déclarées dans CapabilityWhitelist ; elles ne sont pas recopiées ici pour ne pas diverger.
Après rendu, le HTML produit passe par le sanitizer site_public (config/packages/html_sanitizer.yaml) : seuls les éléments et attributs de la liste blanche survivent. Il n'y a ni script, ni style, ni iframe, ni form, et aucun attribut on* n'est jamais conservé.
L'attribut rel des liens¶
Le rendu public recompose l'attribut rel de chaque <a> d'un thème. Un gabarit n'a jamais à écrire ce rel lui-même : les garanties ci-dessous sont ajoutées d'office, à l'affichage, quelle que soit la valeur écrite.
| Garantie | Quand | Résultat |
|---|---|---|
noopener noreferrer |
Sur tout <a>, sans exception |
Protection contre le Reverse Tabnabbing : une page ouverte ne peut pas manipuler l'onglet d'origine. |
nofollow en plus |
Uniquement sur les liens externes | Un lien de thème est présent sur toutes les pages du site (site-wide) — c'est le motif d'une link farm. nofollow retire ce signal des liens sortants. |
Un lien est externe quand l'URL de son href porte un hôte différent de tous les domaines du site. Sont au contraire traités comme internes — donc sans nofollow :
Forme du href |
Interne ? |
|---|---|
URL absolue vers un domaine du site (https://mon-site.fr/a-propos) |
oui |
URL relative (/a-propos, contact.html) |
oui |
Ancre pure (#contenu) |
oui |
Lien mailto: |
oui |
| URL malformée ou sans hôte | oui (repli sûr) |
URL absolue vers un autre hôte (https://exemple.org/…) |
non → nofollow |
La comparaison porte sur les domaines résolus du site courant, pas sur l'en-tête Host de la requête : le rendu public étant mis en cache par site, la décision interne/externe l'est aussi.
rel écrit par l'auteur¶
Un thème peut poser son propre rel (rel="sponsored", rel="ugc", rel="me"…) : rel est un attribut autorisé en entrée sur <a> (voir Syntaxe autorisée et CapabilityWhitelist, src/Plugin/Web/src/Security/CapabilityWhitelist.php). Ses tokens sont fusionnés avec les garanties du rendu, jamais remplacés : l'auteur ajoute, il ne retire pas.
La valeur finale est la réunion, dédupliquée et en minuscules, de :
- les tokens écrits par l'auteur, dans leur ordre d'écriture ;
noopenerpuisnoreferrer;nofollowsi le lien est externe.
href |
rel écrit |
rel rendu |
|---|---|---|
https://exemple.org/x |
(absent) | noopener noreferrer nofollow |
/a-propos |
(absent) | noopener noreferrer |
https://exemple.org/x |
sponsored |
sponsored noopener noreferrer nofollow |
/partenaire |
sponsored |
sponsored noopener noreferrer |
Le contrat est branché sur le profil site_public dans config/packages/html_sanitizer.yaml (l'entrée a y autorise rel en entrée ; la note du fichier détaille la recomposition).
Différence avec les liens du corps d'un article
Les liens écrits dans le corps d'un article (éditeur) passent par un profil de rendu distinct, app.article_renderer, qui force rel="noopener noreferrer" mais jamais nofollow. Un article est une pièce unitaire, pas un élément site-wide : l'auteur y publie des liens qu'il assume, et rien ne les déclasse. Seuls les liens des thèmes reçoivent le traitement nofollow externe décrit ici.
L'emplacement du contenu (content)¶
La variable content marque, dans le corps du thème, l'endroit où le site injecte la page demandée : flux d'articles, article, page spéciale ou aperçu. Un corps minimal se réduit donc à :
Règles de substitution, appliquées par SiteRenderer :
| Cas | Comportement |
|---|---|
content présent une fois, en position de texte |
Le contenu de la page remplace l'emplacement. |
content présent plusieurs fois |
Une seule occurrence est substituée ; les autres restent inertes. |
content absent du corps |
Le contenu est ajouté en fin de zone. Rien n'est masqué ; seule la mise en page est dégradée. |
content placé dans une valeur d'attribut (<div id="…">) |
La substitution est refusée et le contenu est ajouté en fin de zone. |
Le contenu injecté est déjà rendu et assaini par le plugin : il n'est jamais repassé au sanitizer, et la sandbox ne peut ni l'inspecter ni le manipuler.
Exemple : l'en-tête du thème « Par défaut »¶
<a class="site-brand" href="{{ profile.homeUrl }}">{{ profile.title }}</a>
{% if pages is not empty %}
<nav class="site-nav">
{% for page in pages %}
<a href="{{ page.url }}"{% if page.url == profile.currentUrl %} aria-current="page"{% endif %}>{{ page.title }}</a>
{% endfor %}
</nav>
{% endif %}
Source : src/Plugin/Web/themes/default/header.html.twig.
Classes CSS produites par le site¶
Le site produit un HTML de contenu dont les classes sont stables : un thème s'appuie dessus pour styler les pages. Ces classes ne sont pas écrites par le thème, elles lui sont fournies.
| Classe | Émise par | Où |
|---|---|---|
.site-header, .site-main, .site-footer |
Layout | Les trois zones de la page (.site-main porte aussi id="main"). |
.site-feed |
Flux d'articles | Conteneur de la liste des cartes. |
.site-card |
Flux d'articles | Une carte d'article. |
.site-card-title |
Flux d'articles | Titre de la carte (contient le lien). |
.site-card-excerpt |
Flux d'articles | Extrait de la carte. |
.site-card-meta |
Flux d'articles | Date et durée de lecture. |
.site-empty |
Flux d'articles | Message affiché quand aucun article n'est publié. |
.site-pagination |
Flux d'articles | Navigation « Précédent / Suivant » entre pages du flux. |
.site-article |
Page d'article | Conteneur de l'article. |
.site-article-title |
Page d'article, page spéciale | Titre principal. |
.site-article-date |
Page d'article | Date de publication. |
.site-article-body |
Page d'article | Corps rédactionnel (markdown rendu). |
.site-page |
Page spéciale | Corps rédactionnel d'une page spéciale. |
.site-preview-banner |
Aperçu d'article | Bandeau « Aperçu — révision de travail, non publiée. » |
Sources : src/Plugin/Web/templates/site/layout.html.twig, home.html.twig, _article_card.html.twig, article.html.twig, special_page.html.twig et src/Plugin/Web/templates/preview/article.html.twig.
Deux éléments d'accessibilité sont posés par le layout et le socle, et n'ont pas à être stylés par un thème : le lien d'évitement .skip-link (« Aller au contenu », cible #main) et le titre h1.sr-only de la page d'accueil.
Les classes utilisées à l'intérieur des gabarits d'un thème (.site-brand, .site-nav, .site-tagline, .site-colophon dans les thèmes fournis) appartiennent au thème : elles ne font pas partie de ce contrat et peuvent différer d'un thème à l'autre.
Limites du CSS d'un thème¶
La feuille d'un thème est bornée par CssFilter (src/Plugin/Web/src/Security/CssFilter.php), qui lit les mêmes autorisations que la sandbox HTML.
Aucune règle @ — donc pas de @media¶
Les règles @ sont retirées, qu'elles soient à bloc (@media, @supports, @font-face) ou en instruction (@import, @charset). Un thème se rend donc responsive sans media query, avec clamp(), max-width, flex-wrap, minmax() et les unités relatives. C'est une contrainte de conception assumée ; les trois thèmes fournis s'y tiennent.
Propriétés¶
La mise en page est largement ouverte : display, flex et ses dérivées, la grille (grid-template-*, grid-column, grid-row, grid-auto-flow), gap, order, les alignements, les bordures directionnelles (border-top…), les propriétés logiques (margin-inline, padding-block…), overflow, aspect-ratio, object-fit, column-count, la typographie (font-*, line-height, letter-spacing, text-decoration-*, text-wrap, word-break, overflow-wrap), les couleurs, box-shadow, text-shadow, opacity et les listes.
Restent refusées, sans exception : position, z-index, content, transform, filter, clip-path, pointer-events, cursor, animation, transition. Elles ouvriraient une surface de recouvrement, de détournement de clic ou d'injection de texte.
La liste exhaustive des propriétés acceptées est déclarée par CapabilityWhitelist::allowedCssProperties().
Ressources externes¶
Aucune. Les seules url() acceptées sont les data-URI d'image (url(data:image/…)). Une police distante, une image hébergée ailleurs ou une URL relative sont refusées : la liste des hôtes autorisés est vide. Un thème s'appuie donc sur des polices système ou sur les polices du design system.
Motifs interdits¶
Sont retirés en dur, quelle que soit la propriété : expression(, behavior:, -moz-binding, javascript:, `