Aller au contenu
Acecore

Guide d'installation de Sveltia CMS

by Gui
TechnologieCMSAstroCloudflareSécurité
Sommaire
Guide d'installation de Sveltia CMS

Sveltia CMS est utile quand on veut ajouter une interface d’édition à un site statique sans déplacer les contenus vers une base externe. Ce guide reprend la mise en place sur le site Astro d’Acecore et les corrections apparues ensuite dans les PRs et commits.

Le titre est volontairement simple : Guide d’installation de Sveltia CMS. L’objectif est d’aider quelqu’un à l’installer sur son propre site, pas de refaire un comparatif généraliste.

Quand Sveltia CMS est pertinent

Sveltia CMS ne possède pas votre base de données et ne sert pas les contenus via une API séparée. C’est une application SPA qui modifie les fichiers du dépôt via un backend GitHub.

Il est pertinent si :

  • le contenu est en Markdown ou JSON dans le dépôt
  • les changements d’articles, auteurs, tags et textes de pages doivent rester visibles en diff Git
  • vous ne voulez pas ajouter de base de données ni de service admin séparé
  • les images peuvent être stockées dans public/uploads
  • les modifications CMS doivent passer par Pull Request avant production

Pour des permissions éditoriales complexes, une planification avancée ou une grande médiathèque, un headless CMS complet sera plus adapté.

Architecture générale

public/admin/index.html
  -> charge @sveltia/cms depuis un CDN

public/admin/config.yml
  -> définit backend GitHub, collections et médias

workers/sveltia-cms-auth
  -> Cloudflare Worker pour GitHub OAuth

main branch
  -> source unique pour la production

CMS save proxy
  -> valide les chemins autorisés et crée une branche temporaire et une PR par modification

.github/workflows/create-translation-prs.yml
  -> crée des tâches de traduction seulement pour les commits cms:

Installer la page admin n’est qu’un début. Authentification, médias, preview, traduction et merge strategy font partie du design.

1. Placer l’admin dans public/admin

Dans Astro, public est servi comme dossier statique. La documentation Sveltia CMS indique aussi public pour Astro, Next.js, Nuxt, Remix et VitePress.

<!doctype html>
<html lang="fr">
  <head>
    <meta charset="utf-8" />
    <meta name="robots" content="noindex,nofollow" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>CMS</title>
  </head>
  <body>
    <script src="https://unpkg.com/@sveltia/cms@0.172.4/dist/sveltia-cms.js"></script>
  </body>
</html>

N’ajoutez pas de CSS externe ni type="module" sans besoin. Le bundle JavaScript contient déjà les styles nécessaires.

Acecore utilise l’initialisation manuelle pour configurer explicitement le backend. La branche de publication reste main dans tous les environnements.

CMS.init({
  config: {
    backend: {
      branch: 'main',
    },
  },
})

2. Configurer le backend GitHub

Le minimum est backend.name et backend.repo. En production, il faut aussi décider la branche, OAuth et les messages de commit.

backend:
  name: github
  repo: owner/repository
  branch: main
  base_url: https://your-sveltia-cms-auth-worker.example.workers.dev
  api_root: /admin/api/github
  graphql_api_root: /admin/api/graphql
  auth_methods: [oauth]
  commit_messages:
    create: 'cms: create {{collection}} "{{slug}}"'
    update: 'cms: update {{collection}} "{{slug}}"'
    delete: 'cms: delete {{collection}} "{{slug}}"'
    uploadMedia: 'cms: upload "{{path}}"'
    deleteMedia: 'cms: delete media "{{path}}"'

Conservez main comme branche de publication et faites passer les lectures et sauvegardes par un proxy same-origin. Avant de créer une branche temporaire et une PR, le proxy vérifie le dépôt, le droit d’écriture de l’utilisateur GitHub, les chemins modifiés et le dernier HEAD de main.

Au 20 juillet 2026, Editorial Workflow n’est pas implémenté dans Sveltia CMS. Ajouter le paramètre Decap CMS publish_mode: editorial_workflow ne fait pas créer automatiquement des branches temporaires ou des PRs par Sveltia CMS.

Une branche permanente comme cms-content impose une synchronisation continue et augmente le risque de conflits ou d’une mauvaise source de déploiement. Les branches temporaires gardent main comme source unique.

3. Ajouter un OAuth Worker

Un Personal Access Token suffit pour un test, mais pas pour une vraie équipe. Acecore utilise Sveltia CMS Authenticator sur Cloudflare Workers et le configure en base_url.

Le callback de l’application OAuth GitHub pointe vers /callback du Worker. Le Worker reçoit GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET et éventuellement ALLOWED_DOMAINS.

Ce n’est pas le rôle de Turnstile. OAuth protège la connexion au CMS ; Turnstile protège les formulaires ou APIs contre les bots.

4. Fixer le dossier média tôt

Sveltia CMS peut stocker les médias dans le dépôt. Pour Astro, la configuration pratique est :

media_folder: public/uploads
public_folder: /uploads

Acecore a corrigé ce point plus tard dans la PR #116. Il faut décider en même temps le chemin dans le dépôt et l’URL publique.

5. Séparer les collections

collectionCiblePolitique
blogsrc/content/blog/*.mdÉditer seulement les articles source japonais
authorssrc/content/authors/*.jsonÉditer profils et noms localisés
tagssrc/content/tags/*.jsonÉditer tags et noms localisés
page textsrc/i18n/source/ja/**/*.jsonÉditer les textes source japonais des pages et de l’UI

N’exposez pas tous les Markdown traduits sans raison. Acecore garde le japonais comme source canonique et met à jour les traductions via Comment gérer un blog multilingue avec Sveltia CMS.

6. Utiliser relation et select

Les tags doivent être choisis par relation, pas saisis librement.

- name: tags
  label: Tags
  widget: relation
  collection: tags
  value_field: name
  display_fields: ['{{name}} ({{id}})']
  search_fields: [name, id]
  multiple: true
  required: false

Même logique pour auteurs, icônes et styles d’annonce. Un bon CMS empêche autant que possible les valeurs cassées.

7. Éditer les JSON source japonais

Les textes de pages fixes peuvent aussi être exposés. Acecore les centralise dans src/i18n/source/ja/**/*.json.

La leçon : ne pas tout ajouter d’un coup. config.yml grossit vite. Commencez par blog, auteurs, tags, annonces et pages qui changent souvent.

8. Garder main comme branche de publication en preview

Le proxy crée chaque branche temporaire depuis le dernier main. Une preview Cloudflare Pages ne doit donc pas remplacer la branche backend par sa branche de PR. Le résultat est vérifié dans la preview Pages de la PR CMS générée.

CMS.init({
  config: {
    backend: {
      branch: 'main',
    },
  },
})

9. Créer des branches temporaires avec un proxy de sauvegarde

Un proxy de sauvegarde same-origin crée une branche temporaire et une PR vers main pour chaque modification.

backend:
  name: github
  repo: owner/repository
  branch: main
  api_root: /admin/api/github
  graphql_api_root: /admin/api/graphql

Le proxy n’écrit pas directement dans main. Il regroupe les contenus et médias autorisés dans un commit, crée cms/acecore/* depuis le dernier main et ouvre une PR. Après revue et fusion, la branche temporaire est supprimée automatiquement.

Avec GitHub OAuth, le token de l’éditeur sert d’identité et d’acteur d’écriture. Avec Cloudflare Access, une GitHub App propre au site peut être l’acteur. Les restrictions de chemins, branches temporaires, PRs et CI restent communes aux deux variantes.

La méthode de merge compte. Les tâches de traduction dépendent de subjects comme cms: create .... Si un squash les supprime, l’automatisation peut rater le changement. Pour les PRs CMS, préférez merge commit ou rebase merge.

10. Déclencher la traduction seulement pour les commits CMS

La PR #98 a ajouté --cms-only afin que les tâches de traduction liées aux push ne se créent que pour les commits CMS.

function isCmsCommitSubject(subject) {
  return /^cms: (create|update|delete) /.test(subject || '')
}

cms: est un contrat d’automatisation, pas un simple préfixe.

11. Donner son propre CSP à /admin

L’admin doit contacter le CDN, l’API GitHub, l’OAuth Worker et des blob URLs. Acecore sépare donc le CSP de /admin/* et marque cette zone en noindex.

Séparer Turnstile

L’ancienne version mélangeait CMS et Cloudflare Turnstile. C’était confus.

Sveltia CMS concerne le backend GitHub, OAuth, les collections, médias et PRs. Turnstile concerne la protection anti-bot des formulaires ou APIs. Ce sont deux couches différentes.

Leçons des PRs et commits

  • Quand le CMS change, articles et liens internes doivent suivre.
  • OAuth fait partie du vrai setup, pas d’une amélioration future.
  • Les chemins médias doivent être fixés avant les uploads.
  • config.yml doit grandir par étapes.
  • cms: est un contrat pour les workflows.
  • La branche de publication ne change pas selon l’environnement ; la preview vérifie le résultat de la PR CMS.

Point de départ minimal

public/admin/index.html
public/admin/config.yml
public/admin/init.js
public/admin/runtime-config.js

Ajoutez ensuite relations auteurs et tags, images, JSON source, PRs automatiques de CMS et tâches de traduction.

Références

Résumé

Sveltia CMS est facile à placer dans public/admin, mais une installation de production exige de définir branche, OAuth, dossiers médias, politique de langue source, workflow de traduction et stratégie de merge. Avec ces règles, un site Astro reste léger tout en gagnant un processus d’édition fiable.

Flux d'installation de Sveltia CMS

L'admin, l'authentification, les contenus modifiables, les médias et le flux de PR doivent être conçus séparément.

Ajouter l'admin

Placer index.html et config.yml dans public/admin et charger Sveltia CMS.

Configurer GitHub

Définir repo, branche, OAuth Worker et messages de commit avant l'édition.

Limiter le périmètre éditable

Exposer seulement le blog, les auteurs, les tags et les JSON source japonais nécessaires.

Automatiser l'exploitation

Utiliser main comme branche de publication et relier les branches temporaires du proxy de sauvegarde validé, les PRs CMS et les tâches de traduction.

Avant et après le CMS

Markdown édité à la main

  • Seules les personnes à l'aise avec GitHub ou un éditeur peuvent mettre à jour
  • Les chemins d'image, IDs d'auteur et tags sont saisis à la main
  • Source japonaise et traductions peuvent être mélangées
  • La cible de sauvegarde et les chemins modifiables peuvent être ambigus

Édition avec Sveltia CMS

  • Markdown et JSON se modifient dans le navigateur
  • relation, image et select réduisent les valeurs invalides
  • Seuls les commits CMS déclenchent les tâches de traduction
  • Un proxy same-origin écrit uniquement les chemins autorisés dans une branche temporaire et une PR
Checklist de mise en place
  • Terminé : Charger Sveltia CMS depuis public/admin/index.html
  • Terminé : Définir backend GitHub et collections dans public/admin/config.yml
  • Terminé : Utiliser un OAuth Worker pour l'édition multiutilisateur
  • Terminé : Aligner media_folder et public_folder avec le dossier public d'Astro
  • Terminé : Définir comment les commits CMS déclenchent traduction ou publication
Questions fréquentes
Pour quels sites Sveltia CMS est-il adapté ?
Il convient aux sites statiques dont le contenu Markdown ou JSON vit dans le dépôt, comme Astro, Hugo ou VitePress. On ajoute un CMS sans base de données externe.
Un Personal Access Token GitHub suffit-il ?
Oui pour tester, mais pour plusieurs éditeurs ou des profils non techniques, un OAuth Worker est plus sûr et plus simple à expliquer.
Faut-il éditer toutes les langues dans le CMS ?
Pour une petite équipe, il est plus sûr d'éditer seulement la source japonaise dans le CMS et de mettre à jour les traductions par PR.
PartagerX(s'ouvre dans un nouvel onglet)B!Ajouter aux Hatena Bookmarks(s'ouvre dans un nouvel onglet)

Commentaires

Chargement des commentaires...

Les liens, e-mails et textes promotionnels ne peuvent pas être publiés.

G

Gui

PDG d'Acecore. Pilote les systèmes métier, le web, les bases de données et l'infrastructure, la qualité et l'adoption de l'IA, du cadrage des enjeux métier à la conception, au déploiement et à l'amélioration continue. S'appuie sur une capacité pratique en C#/.NET tout en couvrant aussi PHP/JavaScript, SQL Server/PostgreSQL/MySQL et Linux/Windows Server, afin de concevoir les besoins, les choix technologiques, les standards de qualité et les opérations de développement basées sur GitHub comme un flux cohérent. Intègre l'IA générative aux processus de développement, de vérification et d'organisation de l'information, comme une base pratique pour aider les petites équipes à livrer plus vite et plus sûrement.

Cadrage des enjeux métierChoix technologiquesConception de systèmesC#/.NETConception bases de données/infrastructureOpérations de développement GitHubIA générativeConception de flux IAConception de la qualitéIntégration terrain

Envie d'en savoir plus sur nos services ?

Nous offrons un accompagnement complet : développement de systèmes, design web, exploitation de serveurs et design graphique.

Voir les servicesConsultation gratuite

Articles connexes

Concevoir un site Astro + Cloudflare qui grandit fonctionnalité par fonctionnalitéConcevoir un site Astro + Cloudflare qui grandit fonctionnalité par fonctionnalité7 juin 2026 à 19:00
TechnologieAstroCloudflare
Ajouter des commentaires à un blog Astro avec Cloudflare uniquementAjouter des commentaires à un blog Astro avec Cloudflare uniquement7 juin 2026 à 18:00
TechnologieCloudflareAstro
Rendre en sécurité les liens Markdown dans les réponses de chat IARendre en sécurité les liens Markdown dans les réponses de chat IA7 juin 2026 à 14:30
TechnologieSite webIA
Quelle était l’ancienne option SSL payante de Cloudflare ? De Dedicated SSL à Advanced Certificate ManagerQuelle était l’ancienne option SSL payante de Cloudflare ? De Dedicated SSL à Advanced Certificate Manager31 mars 2026
TechnologieCloudflareSécurité
Rechercher sur le site

Après la saisie d'au moins deux caractères, le contenu associé envoie automatiquement vos termes de recherche à Cloudflare Workers AI. Ne saisissez aucune information personnelle ou confidentielle.Traitement des données de recherche