Aller au contenu
Acecore

Guide d'installation de Sveltia CMS

by Gui
Technologie CMS Astro Cloudflare Sé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

cms-content branch
  -> branche où le CMS enregistre les modifications

.github/workflows/cms-content-pr.yml
  -> ouvre une PR de cms-content vers main

.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/[email protected]/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 changer la branche en preview.

CMS.init({
  config: {
    backend: {
      branch: window.ACECORE_CMS_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: cms-content
  base_url: https://your-sveltia-cms-auth-worker.example.workers.dev
  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}}"'

Sur un site personnel, sauvegarder vers main peut suffire. Pour un site d’entreprise ou multilingue, une branche dédiée comme cms-content rend la revue plus sûre.

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. Les previews doivent lire la bonne branche

Si le CMS ouvert dans une preview Cloudflare Pages lit encore main, l’éditeur ne voit pas le même contenu que la preview. Acecore génère public/admin/runtime-config.js avant le build et injecte la branche courante.

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

9. Créer des PRs depuis une branche CMS

Enregistrer dans cms-content puis ouvrir une PR vers main garde la revue claire.

on:
  push:
    branches:
      - cms-content

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.
  • En preview, la branche lue par le CMS doit être claire.

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

Relier la branche cms-content, les PRs de CMS et les tâches de traduction sans les mélanger au développement.

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
  • Une preview peut lire main par erreur

É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
  • runtime config change la branche CMS entre preview et production
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.
Partager X (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, design graphique et éducation IT.

Voir les services Consultation 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
Technologie Astro Cloudflare
Ajouter des commentaires à un blog Astro avec Cloudflare uniquement Ajouter des commentaires à un blog Astro avec Cloudflare uniquement 7 juin 2026 à 18:00
Technologie Cloudflare Astro
Rendre en sécurité les liens Markdown dans les réponses de chat IA Rendre en sécurité les liens Markdown dans les réponses de chat IA 7 juin 2026 à 14:30
Technologie Site web IA
サービスCTAから問い合わせフォームへ文脈を引き継ぐ技術設計 サービスCTAから問い合わせフォームへ文脈を引き継ぐ技術設計 7 juin 2026 à 13:00
Technologie Site web Services
Rechercher des articles