Ir para o conteúdo
Acecore

Guia de instalação do Sveltia CMS

by Gui
Tecnologia CMS Astro Cloudflare Segurança
Índice
Guia de instalação do Sveltia CMS

Sveltia CMS é útil quando você quer adicionar uma tela de edição a um site estático sem mover conteúdo para um banco externo. Este guia resume como ele foi introduzido no site Astro da Acecore e quais ajustes aprendemos com PRs e commits reais.

O título é simples de propósito: Guia de instalação do Sveltia CMS. A meta é ajudar quem quer usar o CMS em outro site, não comparar ferramentas de forma abstrata.

Quando usar Sveltia CMS

Sveltia CMS não controla um banco de dados próprio nem entrega conteúdo por API separada. Ele é um app de administração em SPA que edita arquivos do repositório por meio do GitHub backend.

Ele combina bem quando:

  • o conteúdo vive como Markdown ou JSON no repositório
  • mudanças de artigo, autor, tag e textos de página devem ser revisadas como Git diff
  • você não quer adicionar banco de dados ou serviço administrativo separado
  • uploads podem ficar em public/uploads
  • mudanças do CMS devem passar por Pull Request antes de produção

Se você precisa de permissões editoriais complexas, publicação agendada avançada, grande DAM ou edição em tempo real, um headless CMS completo pode ser melhor.

Arquitetura geral

public/admin/index.html
  -> carrega @sveltia/cms via CDN

public/admin/config.yml
  -> define GitHub backend, collections e pastas de mídia

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

cms-content branch
  -> branch onde o CMS salva edições

.github/workflows/cms-content-pr.yml
  -> abre PR de cms-content para main

.github/workflows/create-translation-prs.yml
  -> cria tarefas de tradução apenas para commits cms:

Instalar a página de admin é só a primeira etapa. Autenticação, mídia, preview, tradução e merge strategy precisam ser parte do desenho.

1. Colocar o admin em public/admin

No Astro, arquivos em public são servidos como estáticos. A documentação do Sveltia CMS também aponta public como pasta estática para Astro, Next.js, Nuxt, Remix e VitePress.

<!doctype html>
<html lang="pt">
  <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ão adicione CSS extra ou type="module" sem motivo. O bundle do Sveltia CMS já inclui os estilos da UI.

Na Acecore usamos inicialização manual para trocar a branch em previews.

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

2. Configurar GitHub backend

O mínimo é backend.name e backend.repo, mas em produção defina também branch, OAuth e mensagens 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}}"'

Para sites pessoais, salvar direto na main pode bastar. Para sites corporativos ou multilíngues, uma branch dedicada como cms-content ajuda na revisão.

3. Adicionar OAuth Worker

Personal Access Token é suficiente para teste, mas não é a melhor opção para vários editores. A Acecore usa Sveltia CMS Authenticator em Cloudflare Workers e aponta base_url para esse Worker.

O callback do GitHub OAuth App aponta para /callback no Worker. O Worker recebe GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET e, se necessário, ALLOWED_DOMAINS.

Isso é diferente de Turnstile. OAuth protege login do CMS; Turnstile protege formulários ou APIs contra bots.

4. Definir a pasta de mídia cedo

Sveltia CMS pode salvar mídia dentro do repositório. Em Astro, o caminho prático é:

media_folder: public/uploads
public_folder: /uploads

A Acecore corrigiu esse ponto depois no PR #116. A lição é decidir o caminho no repositório e a URL pública antes dos primeiros uploads.

5. Separar collections

collectionAlvoPolítica
blogsrc/content/blog/*.mdEditar só artigos fonte em japonês
authorssrc/content/authors/*.jsonEditar perfis e nomes localizados
tagssrc/content/tags/*.jsonEditar tags e nomes localizados
page textsrc/i18n/source/ja/**/*.jsonEditar texto fonte japonês de páginas e UI

Não exponha todos os Markdown traduzidos sem necessidade. A Acecore mantém o japonês como fonte canônica e atualiza traduções por Como operar um blog multilíngue com Sveltia CMS.

6. Usar relation e select

Tags devem ser selecionadas por relation, não digitadas livremente.

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

Autores, ícones e tons de aviso seguem a mesma lógica. CMS bom não só permite editar; ele dificulta salvar valores quebrados.

7. Editar JSON fonte em japonês

Textos fixos também podem entrar no CMS. A Acecore centraliza a fonte japonesa em src/i18n/source/ja/**/*.json e expõe por página.

O cuidado é não adicionar todos os campos de uma vez. config.yml cresce rapidamente. Comece por blog, autores, tags, avisos e páginas que mudam com frequência.

8. Preview deve ler a branch certa

Se o CMS em um preview do Cloudflare Pages ainda lê main, ele mostra conteúdo diferente do preview. A Acecore gera public/admin/runtime-config.js antes do build e injeta a branch atual.

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

9. Criar PRs de uma branch CMS

Salvar em cms-content e abrir PR para main mantém a revisão clara.

on:
  push:
    branches:
      - cms-content

O modo de merge importa. As traduções dependem de subjects como cms: create ... e cms: update .... Se um squash merge apaga esses subjects, a automação pode não detectar a mudança. Para PRs de CMS, preserve os commits cms: com merge commit ou rebase merge.

10. Tradução só para commits CMS

O PR #98 adicionou --cms-only, para que tarefas de tradução por push só sejam criadas com commits CMS.

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

cms: é um contrato de workflow, não decoração.

11. CSP próprio para /admin

O admin precisa conectar ao CDN, GitHub API, OAuth Worker e blob URLs. Por isso, a Acecore separa a CSP de /admin/* e marca a área como noindex.

Separar Turnstile

A versão antiga misturava seleção de CMS e Cloudflare Turnstile. Isso confundia o assunto.

Sveltia CMS trata de backend GitHub, OAuth, collections, mídia e PRs. Turnstile trata de reduzir bots em formulários ou APIs. São camadas diferentes.

Lições de PRs e commits

  • Ao mudar o CMS, atualize também artigos e links internos.
  • OAuth deve fazer parte do setup real.
  • Caminhos de mídia devem ser definidos antes de uploads.
  • config.yml deve crescer por etapas.
  • cms: é contrato de automação.
  • Preview precisa deixar clara a branch lida pelo CMS.

Ponto inicial mínimo

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

Depois adicione relations de autores e tags, imagens, JSON fonte, PRs automáticos de CMS e tarefas de tradução.

Referências

Resumo

Sveltia CMS é simples de colocar em public/admin, mas a instalação de produção exige decidir branch, OAuth, pastas de mídia, política de idioma fonte, workflow de tradução e merge strategy. Com essas regras claras, um site Astro continua estático e leve, mas ganha uma operação de conteúdo muito mais utilizável.

Fluxo de instalação do Sveltia CMS

A área administrativa, autenticação, conteúdo editável, mídia e fluxo de PR devem ser pensados separadamente.

Adicionar o admin

Coloque index.html e config.yml em public/admin e carregue o Sveltia CMS.

Configurar GitHub

Defina repo, branch, OAuth Worker e mensagens de commit antes de começar a editar.

Limitar o escopo editável

Exponha apenas blog, autores, tags e JSON fonte em japonês que devem ser editados pelo CMS.

Automatizar a operação

Conecte a branch cms-content, PRs de CMS e tarefas de tradução sem misturar com desenvolvimento normal.

Antes e depois do CMS

Markdown editado manualmente

  • Só quem usa GitHub ou editor atualiza com facilidade
  • Caminhos de imagem, IDs de autor e tags são digitados à mão
  • Fonte japonesa e traduções podem ser misturadas
  • Preview pode ler conteúdo da main por engano

Edição com Sveltia CMS

  • Markdown e JSON são editados em formulários no navegador
  • relation, image e select reduzem valores inválidos
  • Apenas commits de CMS disparam tarefas de tradução
  • runtime config troca a branch do CMS entre preview e produção
Checklist de instalação
  • Concluído: Carregar Sveltia CMS em public/admin/index.html
  • Concluído: Definir GitHub backend e collections em public/admin/config.yml
  • Concluído: Usar OAuth Worker para edição por várias pessoas
  • Concluído: Alinhar media_folder e public_folder ao diretório public do Astro
  • Concluído: Decidir como commits de CMS acionam tradução ou publicação
Perguntas frequentes
Para que tipo de site o Sveltia CMS serve?
Ele funciona bem para sites estáticos onde Markdown ou JSON ficam no repositório, como Astro, Hugo e VitePress. Assim é possível adicionar CMS sem banco de dados externo.
Posso usar só um Personal Access Token do GitHub?
Pode, mas para várias pessoas ou editores não técnicos, um OAuth Worker é mais seguro e fácil de explicar. A Acecore usa Cloudflare Worker como cliente OAuth.
Devo editar todos os idiomas no CMS?
Em uma equipe pequena, é mais seguro editar apenas a fonte japonesa e atualizar traduções por PR. Expor todos os idiomas dificulta revisão e detecção de traduções desatualizadas.
Compartilhar X (abre em nova aba) B! Adicionar ao Hatena Bookmark (abre em nova aba)

Comentários

Carregando comentários...

Links, e-mails e textos promocionais não podem ser publicados.

G

Gui

CEO da Acecore. Lidera sistemas de negócio, web, bancos de dados e infraestrutura, qualidade e adoção de IA da definição de problemas de negócio ao design, implantação e melhoria após o lançamento. Parte de capacidade prática em C#/.NET e também cobre PHP/JavaScript, SQL Server/PostgreSQL/MySQL e Linux/Windows Server, desenhando requisitos, escolhas tecnológicas, padrões de qualidade e operações de desenvolvimento baseadas em GitHub como um fluxo único. Incorpora IA generativa a processos de desenvolvimento, verificação e organização de informações, como uma base prática para que equipes pequenas entreguem mais rápido e com maior confiabilidade.

Definição de problemas de negócioSeleção tecnológicaDesign de sistemasC#/.NETDesign de bancos de dados/infraestruturaOperações de desenvolvimento no GitHubIA generativaDesign de fluxos de IADesign de qualidadeIntegração em campo

Quer saber mais sobre nossos serviços?

Oferecemos suporte abrangente em desenvolvimento de sistemas, design web, design gráfico e educação em TI.

Ver serviços Consulta gratuita

Artigos relacionados

Como projetar um site Astro + Cloudflare que cresce por funcionalidade Como projetar um site Astro + Cloudflare que cresce por funcionalidade 7 de junho de 2026 às 19:00
Tecnologia Astro Cloudflare
Como adicionar comentários a um blog Astro usando apenas Cloudflare Como adicionar comentários a um blog Astro usando apenas Cloudflare 7 de junho de 2026 às 18:00
Tecnologia Cloudflare Astro
Renderizar links Markdown com segurança em respostas de chat com IA Renderizar links Markdown com segurança em respostas de chat com IA 7 de junho de 2026 às 14:30
Tecnologia Site IA
サービスCTAから問い合わせフォームへ文脈を引き継ぐ技術設計 サービスCTAから問い合わせフォームへ文脈を引き継ぐ技術設計 7 de junho de 2026 às 13:00
Tecnologia Site Serviços
Pesquisar artigos