#Guides
La référence dit ce qu’est chaque chose. Les guides disent dans quel ordre les faire. Cinq parcours, chacun mené du début à la fin, avec ce qu’on doit voir à l’écran pour savoir que l’étape a marché.
Si tu n’as jamais touché à un thème Webcosa, commence par Créer son premier thème : les quatre autres partent du principe que tu as déjà un thème installé et un CLI connecté.
#Ce que tous les guides supposent
Trois choses, et il vaut mieux les régler une fois pour toutes avant de lire quoi que ce soit.
Un site Webcosa actifrequisLe CLI et l’API travaillent sur un site, jamais dans le vide. Un site dont
l’essai est terminé refuse toute écriture de thème avec un 402 — c’est la
garde exigerSiteActif, et elle porte sur l’apparence en priorité, puisque la
changer reviendrait à modifier ce que voient des visiteurs alors qu’on ne
publie plus.
Node.js≥ 20.13requisNode 22 LTS ou 24 est le choix recommandé. Le CLI n’a aucune dépendance :
scripts/theme.mjs et rien d’autre. Pas de npm install, pas de
node_modules, pas de paquet à mettre à jour. Le plancher de 20.13 est
justifié sur Installation.
Une clé d’API de portée `themes`La portée lecture suffit à lister et recuperer. Tout ce qui écrit —
pousser, suivre, publier — exige themes. Voir
Connexion.
#Le fait qui change tout, et qu’il vaut mieux connaître d’entrée
Un thème brouillon ne se prévisualise pas. Il n’existe aucune adresse, dans
le CMS ou ailleurs, qui rende un site avec un thème non publié : le rendu
public cherche le thème dont le rôle est publie, et lui seul. « Voir le
site », dans l’éditeur de code comme dans le menu d’un brouillon, ouvre
toujours l’adresse publique — donc le thème en ligne.
Ce n’est pas un oubli de cette documentation, c’est l’état du produit. La conséquence pratique tient en une ligne : pour regarder ce qu’on écrit, il faut que le thème soit publié quelque part. Les guides ci-dessous tournent tous autour de cette contrainte, et chacun dit comment la contourner sans casser un site que des clients regardent.
Le contournement le plus propre, dès qu’un site est réellement en ligne : un
second site dans le même compte, qui sert de préproduction. Le CLI vise le
site avec --site=<slug>, donc changer de cible ne demande qu’une option — et
.webcosa.json la fige par dossier. Voir Configuration.
#Deux chemins qui ne se rejoignent pas
C’est la source de confusion numéro un, et elle mérite d’être posée avant tout le reste : un thème peut vivre à deux endroits.
| Le catalogue | Un site | |
|---|---|---|
| Où | themes/<id>/, dans le dépôt du CMS | table theme_fichiers, en base |
| Pour qui | tous les sites, à l’installation | un seul site |
| On l’édite avec | son éditeur, puis node scripts/compiler-themes.mjs | le CLI, ou l’éditeur de code du CMS |
| Il se déploie | avec le CMS | tout de suite, à la publication |
Rien ne circule automatiquement de l’un à l’autre. L’installation copie
les fichiers du catalogue dans la base du site ; corriger un thème d’origine ne
corrige aucun site déjà installé. Dans l’autre sens, un thème travaillé au CLI
ne remonte pas dans themes/ — git status ne montrera jamais rien, le
travail est en base.
Le seul pont est manuel, et Ajouter un thème au catalogue le décrit en entier.