Ir al contenido
Acecore

Guía de instalación de Sveltia CMS

by Gui
TecnologíaCMSAstroCloudflareSeguridad
Índice
Guía de instalación de Sveltia CMS

Sveltia CMS encaja cuando quieres añadir una pantalla de edición a un sitio estático sin mover el contenido a una base de datos externa. Esta guía resume cómo lo incorporamos en el sitio Astro de Acecore y qué corregimos después al revisar PRs y commits reales.

El título es simple a propósito: Guía de instalación de Sveltia CMS. No es una comparación de CMS, sino una referencia práctica para quien quiera introducirlo en su propio sitio.

Cuándo usar Sveltia CMS

Sveltia CMS no es un CMS que posea una base de datos y sirva contenido por API. Es una aplicación de una sola página que edita archivos del repositorio mediante GitHub backend.

Es buena opción cuando:

  • el contenido está en Markdown o JSON dentro del repositorio
  • quieres revisar artículos, autores, etiquetas y textos de página como diffs de Git
  • no quieres añadir base de datos ni servicio de administración separado
  • las imágenes pueden guardarse bajo public/uploads
  • los cambios del CMS deben pasar por Pull Request antes de producción

Si necesitas permisos editoriales complejos, publicación programada avanzada, mucha gestión de medios o edición de datos en tiempo real, puede convenir un headless CMS completo o un panel propio.

Arquitectura general

La configuración de Acecore se organiza así:

public/admin/index.html
  -> carga @sveltia/cms desde CDN

public/admin/config.yml
  -> define GitHub backend, collections y carpetas de medios

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

main branch
  -> única fuente de verdad para producción

CMS save proxy
  -> valida las rutas permitidas y crea una rama temporal y un PR por cada cambio

.github/workflows/create-translation-prs.yml
  -> crea tareas de traducción solo para commits cms:

Instalar la pantalla admin es solo el inicio. Autenticación, rutas de imágenes, preview branches, traducciones y estrategia de merge forman parte del diseño.

1. Colocar el admin en public/admin

En Astro, public se sirve como archivos estáticos. La documentación de Sveltia CMS también indica public como carpeta estática para Astro, Next.js, Nuxt, Remix y VitePress.

<!doctype html>
<html lang="es">
  <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>

No añadas una hoja CSS extra ni type="module" sin necesidad. La UI ya viene empaquetada en el JavaScript de Sveltia CMS.

Acecore usa inicialización manual para configurar el backend de forma explícita. La rama de publicación sigue siendo main en todos los entornos.

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

2. Configurar GitHub backend

Lo mínimo es backend.name y backend.repo, pero en producción conviene definir también branch, OAuth y mensajes 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}}"'

Mantén main como rama de publicación y dirige lecturas y guardados por un proxy same-origin. Antes de crear una rama temporal y un PR, el proxy valida el repositorio, el permiso de escritura del usuario de GitHub, las rutas modificadas y el HEAD más reciente de main.

A 20 de julio de 2026, Editorial Workflow no está implementado en Sveltia CMS. Añadir la opción de Decap CMS publish_mode: editorial_workflow no hace que Sveltia CMS cree ramas temporales o PRs automáticamente.

Una rama permanente como cms-content exige sincronización continua y aumenta el riesgo de conflictos o de configurar mal el origen del despliegue. Las ramas temporales mantienen main como única fuente de verdad.

3. Añadir OAuth Worker

Un Personal Access Token sirve para probar, pero no es ideal para varios editores. Acecore usa Sveltia CMS Authenticator en Cloudflare Workers y lo configura en base_url.

La aplicación OAuth de GitHub apunta su callback a /callback del Worker. El Worker recibe GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET y opcionalmente ALLOWED_DOMAINS.

Esto no sustituye a Turnstile. OAuth protege el inicio de sesión del CMS; Turnstile protege formularios o APIs de comentarios frente a bots.

4. Fijar la carpeta de medios desde el principio

Sveltia CMS puede guardar medios dentro del repositorio. En Astro, lo práctico es usar public/uploads y publicarlo como /uploads.

media_folder: public/uploads
public_folder: /uploads

Acecore corrigió este punto después en PR #116. La lección es decidir juntos la ubicación en el repositorio y la URL pública antes de que editores empiecen a subir imágenes.

5. Separar el alcance en collections

collectionObjetivoPolítica
blogsrc/content/blog/*.mdEditar solo artículos fuente en japonés
authorssrc/content/authors/*.jsonEditar perfiles y nombres localizados
tagssrc/content/tags/*.jsonEditar etiquetas y nombres localizados
page textsrc/i18n/source/ja/**/*.jsonEditar textos fuente de páginas y UI común

No expongas todos los Markdown traducidos si no es necesario. Acecore trata el japonés como fuente canónica y actualiza traducciones mediante Cómo gestionar un blog multilingüe con Sveltia CMS.

6. Reducir errores con relation y select

Las etiquetas son relation fields, no texto libre.

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

Autores, iconos y tonos de anuncios siguen la misma idea. Un buen CMS no solo permite editar; dificulta guardar valores inválidos.

7. Editar también JSON fuente japonés

Los textos fijos de páginas pueden gestionarse igual. Acecore reúne la fuente japonesa en src/i18n/source/ja/**/*.json y la expone por página.

La advertencia es no añadir todos los campos de golpe. config.yml crece rápido y se vuelve difícil de revisar. Empieza por blog, autores, etiquetas, avisos y páginas que cambian a menudo.

8. Mantener main como rama de publicación en preview

El proxy crea cada rama temporal desde el último main. Por eso una preview de Cloudflare Pages no debe sustituir la rama backend por su rama de PR. El resultado se revisa en la preview Pages del PR de CMS generado.

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

9. Crear ramas temporales con un proxy de guardado

Un proxy de guardado same-origin crea una rama temporal y un PR hacia main para cada cambio.

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

El proxy no escribe directamente en main. Reúne contenido y medios permitidos en un commit, crea cms/acecore/* desde el último main y abre un PR. Tras revisarlo y fusionarlo, la rama temporal se elimina automáticamente.

Con GitHub OAuth, el token del editor aporta identidad y actúa como escritor. Con Cloudflare Access, una GitHub App específica del sitio puede ser el actor. Las restricciones de rutas, ramas temporales, PRs y CI son comunes a ambas variantes.

La forma de merge importa. Las tareas de traducción dependen de subjects como cms: create ... o cms: update .... Si se hace squash y se pierden, la automatización puede no detectar el cambio. Para PRs CMS, conviene merge commit o rebase merge.

10. Activar traducción solo con commits CMS

PR #98 añadió --cms-only para que las tareas de traducción por push solo se creen con commits de CMS.

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

cms: es parte del contrato de workflow, no un prefijo decorativo.

11. Usar CSP propio para /admin

La pantalla admin necesita conectar con CDN, GitHub API, OAuth Worker y blob URLs. Por eso Acecore separa el CSP de /admin/* y además lo marca como noindex.

Separar Turnstile

La versión antigua mezclaba selección de CMS y Cloudflare Turnstile. Eso confundía el foco.

Sveltia CMS trata de GitHub backend, OAuth, collections, medios y PRs. Turnstile trata de reducir bots en formularios o APIs. Ambos ayudan a la operación, pero viven en capas distintas.

Lecciones de PRs y commits

  • Al cambiar de CMS, también hay que actualizar artículos, screenshots y enlaces internos.
  • OAuth debe formar parte del setup real, no quedar para después.
  • Las rutas de medios deben fijarse antes de subir imágenes.
  • config.yml debe crecer por etapas.
  • cms: es un contrato para automatización.
  • La rama de publicación no cambia por entorno; la preview comprueba el resultado del PR de CMS.

Punto de partida mínimo

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

Desde ahí, añade relations de autores y etiquetas, imágenes, JSON fuente, PRs automáticos de CMS y tareas de traducción.

Referencias

Resumen

Sveltia CMS es fácil de colocar bajo public/admin, pero la instalación productiva requiere definir branch, OAuth, carpetas de medios, política de idioma fuente, workflow de traducción y estrategia de merge. Con esas reglas claras, un sitio Astro puede seguir siendo estático y ligero, pero mucho más fácil de actualizar.

Flujo de instalación de Sveltia CMS

La pantalla de administración, autenticación, contenido editable, medios y flujo de PR deben diseñarse por separado.

Añadir la pantalla admin

Coloca index.html y config.yml en public/admin y carga Sveltia CMS.

Configurar GitHub

Define repo, branch, OAuth Worker y mensajes de commit antes de usar el CMS.

Limitar el alcance editable

Expón solo blog, autores, etiquetas y JSON fuente japonés que realmente deban editarse.

Automatizar la operación

Usa main como rama de publicación y conecta ramas temporales del proxy de guardado validado, PRs de CMS y tareas de traducción.

Antes y después de añadir CMS

Markdown editado a mano

  • Solo quienes usan GitHub o un editor pueden actualizar fácilmente
  • Rutas de imagen, IDs de autor y etiquetas se escriben a mano
  • Cambios de fuente japonesa y traducciones se mezclan con facilidad
  • El destino de guardado y las rutas editables pueden quedar ambiguos

Edición con Sveltia CMS

  • Markdown y JSON se editan desde formularios del navegador
  • relation, image y select reducen valores inválidos
  • Solo commits de CMS disparan tareas de traducción
  • Un proxy same-origin escribe solo rutas permitidas en una rama temporal y un PR
Lista de verificación
  • Completado: Cargar Sveltia CMS desde public/admin/index.html
  • Completado: Definir GitHub backend y collections en public/admin/config.yml
  • Completado: Usar OAuth Worker para edición multiusuario
  • Completado: Alinear media_folder y public_folder con el directorio public de Astro
  • Completado: Decidir cómo los commits CMS activan traducción o publicación
Preguntas frecuentes
¿Para qué sitios sirve Sveltia CMS?
Funciona bien en sitios estáticos donde Markdown o JSON viven en el repositorio, como Astro, Hugo o VitePress. Permite añadir CMS sin una base de datos externa.
¿Puedo usar solo un Personal Access Token de GitHub?
Sí, pero para varios editores o personas no técnicas, un OAuth Worker es más seguro y fácil de explicar. Acecore lo ejecuta en Cloudflare Workers y lo configura como backend.base_url.
¿Conviene editar todos los idiomas en el CMS?
En equipos pequeños es más seguro editar solo la fuente japonesa y actualizar las traducciones mediante PRs. Exponer todos los idiomas complica revisión y detección de traducciones obsoletas.
CompartirX(se abre en nueva pestaña)B!Añadir a Hatena Bookmark(se abre en nueva pestaña)

Comentarios

Cargando comentarios...

No se pueden publicar enlaces, correos ni textos promocionales.

G

Gui

CEO de Acecore. Lidera sistemas de negocio, web, bases de datos e infraestructura, calidad y adopción de IA desde la definición de problemas de negocio hasta el diseño, la puesta en marcha y la mejora posterior. Se apoya en capacidad práctica con C#/.NET y también cubre PHP/JavaScript, SQL Server/PostgreSQL/MySQL y Linux/Windows Server, diseñando requisitos, selección tecnológica, estándares de calidad y operaciones de desarrollo basadas en GitHub como un flujo coherente. Incorpora la IA generativa en procesos de desarrollo, verificación y organización de información, como una base práctica para que equipos pequeños entreguen más rápido y con mayor fiabilidad.

Definición de problemas de negocioSelección tecnológicaDiseño de sistemasC#/.NETDiseño de bases de datos/infraestructuraOperaciones de desarrollo en GitHubIA generativaDiseño de flujos de IADiseño de calidadIntegración en sitio

¿Quiere saber más sobre nuestros servicios?

Ofrecemos soporte integral en desarrollo de sistemas, diseño web, operaciones de servidores y diseño gráfico.

Ver serviciosConsulta gratuita

Artículos relacionados

Diseñar un sitio Astro + Cloudflare que crece función por funciónDiseñar un sitio Astro + Cloudflare que crece función por función7 de junio de 2026 a las 19:00
TecnologíaAstroCloudflare
Cómo añadir comentarios a un blog Astro usando solo CloudflareCómo añadir comentarios a un blog Astro usando solo Cloudflare7 de junio de 2026 a las 18:00
TecnologíaCloudflareAstro
Renderizar con seguridad enlaces Markdown en respuestas de chat con IARenderizar con seguridad enlaces Markdown en respuestas de chat con IA7 de junio de 2026 a las 14:30
TecnologíaSitio webIA
Qué era realmente la opción SSL de pago de Cloudflare: de Dedicated SSL a Advanced Certificate ManagerQué era realmente la opción SSL de pago de Cloudflare: de Dedicated SSL a Advanced Certificate Manager31 de marzo de 2026
TecnologíaCloudflareSeguridad
Buscar en el sitio

Al introducir al menos dos caracteres, Contenido relacionado envía automáticamente sus términos de búsqueda a Cloudflare Workers AI. No introduzca información personal ni confidencial.Tratamiento de los datos de búsqueda