#Ajouter un thème au catalogue

Le catalogue, ce sont les thèmes d’origine : ceux qu’un client trouve dans Site web → Installer un thème, à côté d’Origo, Forge, Vela et Piazza. Ils vivent dans le dépôt du CMS, sous Git, et se déploient avec lui. Ce guide dit comment en ajouter un — et pourquoi l’étape de compilation, qui a l’air d’une formalité, est celle qui casse la production quand on l’oublie.

#Les deux catalogues, à ne pas confondre

Le mot « thème » désigne deux choses différentes dans ce produit, et elles ne se recoupent pas.

Cette page ne parle que de la première colonne. Ajouter un thème au Store se fait dans src/lib/store/themes.ts et n’a rien à voir avec Liquid.

#Le parcours

1. Créer le dossier

   Le nom du dossier est l’identifiant du thème. Il voyage : c’est lui qui est enregistré dans la colonne origine de chaque thème installé, et c’est lui qui sert à ne pas proposer deux fois le même à l’installation. Choisis-le court, en minuscules, et ne le renomme plus ensuite.

   $mkdir -p themes/atelier/{layout,sections,snippets,assets,config,templates}

   Les six dossiers, et rien d’autre. La compilation descend récursivement mais le format ne connaît que deux segments : un fichier plus profond serait embarqué dans le module et refusé à l’installation, ce qui ferait échouer le thème entier chez le premier client qui l’essaie.

2. Écrire les trois fichiers indispensables

   Sans eux, l’installation est refusée : POST /api/themes répond 400 avec {"error":"fichier_requis_manquant"}.

   layout/theme.liquidrequis

   La coquille HTML de toutes les pages, avec content_for_layout. Un thème publié qui la perd est purement ignoré : le site repart sur l’ancien moteur, sans une erreur. Voir La coquille.

   templates/index.jsonrequis

   La composition de la page d’accueil. C’est le thème qui compose l’accueil — un site n’a pas besoin d’avoir créé une page pour qu’elle rende.

   config/settings_schema.jsonrequis

   Les réglages globaux, déclarés. Un tableau de groupes, chacun avec un name et des settings.

   Le plus rapide, et de loin : partir d’un thème existant.

   $cp -R themes/forge/. themes/atelier/

3. Renseigner config/theme.json

   C’est ce fichier qui donne au thème son identité dans l’écran d’installation.

   themes/atelier/config/theme.jsonjson

   {
     "nom": "Atelier",
     "version": "1.0.0",
     "pour": "Robuste et net, pour les métiers de la main. Traits épais, titres en capitales, aucune ombre.",
     "metiers": ["artisan", "batiment", "services"],
     "traits": [
       "Prestations numérotées, séparées par des filets",
       "Réalisations en grille asymétrique, la première en grand",
       "Téléphone dans l'en-tête, cliquable sur mobile"
     ]
   }

   nomchaînerequis

   Le nom affiché partout : la carte d’installation, la liste des thèmes du site, lister du CLI. Sans lui, la compilation retombe sur l’identifiant du dossier — ce qui se voit, et c’est le but.

   versionchaînedéfaut : 1.0.0

   Recopiée dans la ligne du thème installé. Elle ne bouge pas toute seule : c’est une étiquette, pas un mécanisme de mise à jour. Un thème installé ne se met jamais à jour depuis le catalogue.

   pourchaîne

   Une phrase : à qui il va, et pourquoi. Affichée sous le nom, sur la carte d’installation. C’est elle qui décide du clic — écris-la comme une réponse à « pourquoi celui-là plutôt qu’un autre ».

   traitschaîne[]

   Trois traits, affichés en liste sous la description. Dis ce qui distingue réellement le thème, pas ce que tous ont : « Horaires affichés dans l’en-tête, pas cachés dans le pied » vaut mieux que « Design responsive ».

   metierschaîne[]

   Les familles de métiers visées — les identifiants de src/lib/metiers.ts : batiment, artisan, beaute, sante, conseil, juridique, image, restauration, commerce, services, formation, autre.

   Déclaratif aujourd’hui : l’écran d’installation ne filtre pas par métier, il n’affiche que nom, pour et traits. Renseigne-le quand même, c’est le champ sur lequel un filtre s’appuiera.

   Note

   Un theme.json illisible n’arrête pas la compilation : le thème part avec son identifiant comme nom et 1.0.0 comme version. C’est délibéré — un JSON cassé ne doit pas empêcher les trois autres thèmes de se compiler — mais le défaut se voit à l’écran, et c’est ainsi qu’on l’attrape.

4. Compiler le catalogue

   $node scripts/compiler-themes.mjs5 thèmes, 151 fichiers → src/lib/liquid/catalogue.ts

   Le script parcourt themes/, embarque tout fichier en .liquid, .json, .css ou .svg, et écrit un module TypeScript généré. Les autres extensions sont ignorées : un README.md ou une capture d’écran posée dans le dossier ne partira pas au catalogue.

   Relis le compte affiché. Si le nombre de thèmes n’a pas augmenté, le dossier n’est pas là où tu crois.

5. Vérifier en installant

   Lance le CMS, ouvre Site web sur un site de test, et regarde la section Installer un thème.

   Ce que tu dois voir : une carte « Atelier », avec sa phrase et ses trois traits. Clique Installer : le message « « Atelier » est installé, en brouillon. » doit apparaître, et la carte disparaître de la liste — on ne propose pas deux fois le même thème au même site.

   C’est le seul test qui vaille : l’installation passe les fichiers par la même validation que l’import d’une archive extérieure. Nos propres thèmes n’y ont aucun privilège, et c’est voulu — un thème d’origine mal formé doit être arrêté ici plutôt que découvert par un client.

   Attention

   Ouvre l’onglet réseau avant de cliquer. Sur l’action « installer », l’API répond {"error":"…"} sans champ message, et l’écran affiche donc le libellé générique « L’opération n’a pas abouti. » — le même pour les cinq causes ci-dessous. Seuls l’import et la duplication rendent une phrase lisible. La cause exacte est dans le corps de la réponse, et nulle part ailleurs.

   Ce que répond POST /api/themes	Ce qu’il faut corriger
   fichier_requis_manquant	il manque layout/theme.liquid, templates/index.json ou config/settings_schema.json
   chemin_invalide	un fichier à plus de deux segments, ou une extension refusée dans son dossier
   fichier_trop_gros	un fichier au-dessus de 512 Ko
   trop_de_fichiers	plus de 120 fichiers
   theme_inconnu	l’identifiant envoyé n’existe pas dans le module compilé — presque toujours une compilation oubliée

6. Commiter le module généré

   $git add themes/atelier src/lib/liquid/catalogue.ts

   src/lib/liquid/catalogue.ts est versionné. C’est ce qui rend l’oubli visible : un git status qui montre themes/atelier/ sans catalogue.ts dit que la compilation n’a pas été relancée. Prends l’habitude de regarder les deux ensemble.

#Pourquoi la compilation n’est pas optionnelle

C’est la question qu’on se pose en voyant un script de génération, et la réponse mérite d’être connue avant de proposer de le supprimer.

Un thème est fait de fichiers, et on veut les éditer comme des fichiers : coloration syntaxique, recherche, diff lisible en revue. Les écrire dans des chaînes TypeScript rendrait chaque accolade Liquid pénible à taper et chaque revue illisible.

Mais le rendu ne peut pas les relire depuis le disque. Sur Vercel, seul ce que l’empaqueteur a vu est embarqué dans la fonction. Un readFileSync sur themes/ marcherait parfaitement en développement — le dossier est là, à côté — et rendrait « fichier introuvable » en production.

Corollaire pratique : une modification dans themes/ n’existe pour personne tant que compiler-themes.mjs n’a pas tourné. Ni pour le CMS local, ni pour le déploiement. Il n’y a pas de rechargement à chaud sur ce chemin.

#Ce que le catalogue ne fait pas

Trois propriétés contre-intuitives, et elles découlent toutes de la même décision : l’installation copie.

#Le pont, et il est manuel

Faire d’un thème travaillé sur un site un thème de catalogue demande de le rapatrier soi-même. C’est le seul chemin, et il n’y en aura pas d’autre tant que personne n’aura décidé qui, du disque ou de la base, fait autorité.

1. Récupérer le thème dans themes/

   $node scripts/theme.mjs recuperer --theme=Atelier --dossier=themes/atelier

   Le CLI avertit au passage :

   Sortie du CLI

   ! themes/atelier est sous le `themes/` du dépôt — celui des thèmes d'ORIGINE,
     compilé dans le catalogue. Préfère `--dossier=` ailleurs.

   Cet avertissement n’est pas là pour t’arrêter ici : il est là pour que ce soit une décision, et non le résultat d’un --dossier mal choisi un soir de fatigue. Un thème récupéré là finirait au catalogue, proposé à tous les sites, sans que personne l’ait voulu.

2. Nettoyer ce qui ne doit pas partir

   recuperer pose un .webcosa.json dans le dossier : il nomme le site et le thème d’où vient la copie. Il n’a rien à faire dans le catalogue.

   $rm themes/atelier/.webcosa.json

   Relis aussi config/settings_data.json : ce sont les valeurs de ce client-là — son téléphone, son adresse, ses horaires. Elles deviendraient les valeurs par défaut de tous les sites qui installent le thème.

3. Compiler et vérifier

   $node scripts/compiler-themes.mjs5 thèmes, 151 fichiers → src/lib/liquid/catalogue.ts

   Puis installe-le sur un site de test, comme plus haut. Un thème qui vient d’un site réel a souvent accumulé des fichiers que le format tolère mal — c’est le moment de s’en apercevoir.

#Retirer un thème du catalogue

Supprime le dossier, recompile. Le thème disparaît de l’écran d’installation.

Les sites qui l’avaient installé, eux, ne perdent rien : leurs fichiers sont en base, indépendants. La seule trace qui reste est la valeur de leur colonne origine, qui pointe désormais vers un identifiant sans modèle — sans conséquence, puisqu’elle ne sert qu’à filtrer la liste des thèmes proposés.

#La suite