Communitygithub.com

ovachiever/droid-tings

Configure o Sveltia CMS - o sistema de gerenciamento de conteúdo leve e baseado em Git, sucessor do Decap/Netlify CMS, com bundle 5x menor (300 KB), desempenho GraphQL e mais de 260 problemas corrigidos do antecessor. Agnóstico de framework para Hugo, Jekyll, 11ty, Gatsby, Astro.

O que é droid-tings?

Esta skill configura e integra o Sveltia CMS em projetos de sites estáticos. O Sveltia CMS é um sucessor moderno e leve do Decap CMS (antigo Netlify CMS), oferecendo uma interface de edição rápida e intuitiva para conteúdo armazenado em repositórios Git. Suas principais vantagens incluem um tamanho de bundle extremamente reduzido (menos de 500 KB), uso de APIs GraphQL para carregamento instantâneo de conteúdo, suporte a temas escuros e otimização de imagens integrada. A skill fornece guias de configuração detalhados para vários frameworks (Hugo, Jekyll, 11ty, Astro, Gatsby, Next.js, SvelteKit), instruções para autenticação OAuth via Cloudflare Workers ou Vercel, e exemplos de configuração YAML para diferentes estruturas de conteúdo. Ela também aborda cenários comuns de migração a partir do Decap/Netlify CMS e solução de problemas de autenticação, erros de parse YAML e políticas CORS.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ovachiever/droid-tings/tree/HEAD/skills/sveltia-cms

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Skill Sveltia CMS

Skill completa para integrar o Sveltia CMS em projetos de sites estáticos.


O que é o Sveltia CMS?

Sveltia CMS é um sistema de gerenciamento de conteúdo headless leve e baseado em Git, construído do zero como sucessor moderno do Decap CMS (antigo Netlify CMS). Ele fornece uma interface de edição rápida e intuitiva para conteúdo armazenado em repositórios Git.

Principais Características

  1. Leve e Rápido

    • Tamanho do bundle: <500 KB (minificado/brotli) vs 1.5-2.6 MB dos concorrentes
    • Construído com o compilador Svelte (sem overhead de DOM virtual)
    • Utiliza APIs GraphQL para busca instantânea de conteúdo
    • Pesquisa baseada em relevância em todo o conteúdo
  2. Experiência do Usuário Moderna

    • Interface administrativa intuitiva com aproveitamento total da viewport
    • Suporte a modo escuro (segue as preferências do sistema)
    • Otimizado para dispositivos móveis e tablets
    • Upload de arquivos por arrastar e soltar com suporte a múltiplos arquivos
    • Visualização em tempo real com atualizações instantâneas
  3. Arquitetura Nativa Git

    • Conteúdo armazenado como Markdown, MDX, YAML, TOML ou JSON
    • Controle de versão completo e histórico de alterações
    • Sem dependência de fornecedor - o conteúdo vive com o código
    • Suporte aos backends GitHub, GitLab, Gitea, Forgejo
  4. Agnóstico de Framework

    • Servido como bundle JavaScript vanilla
    • Funciona com Hugo, Jekyll, 11ty, Gatsby, Astro, Next.js, SvelteKit
    • Sem dependências de runtime de React, Vue ou framework
    • Compatível com qualquer gerador de site estático
  5. Internacionalização de Primeira Classe

    • Suporte a múltiplos idiomas integrado
    • Integração de tradução DeepL com um clique
    • Alternância de localidade durante a edição
    • Estruturas i18n flexíveis (arquivos, pastas, arquivo único)
  6. Otimização de Imagem Integrada

    • Conversão automática para WebP
    • Redimensionamento e otimização no lado do cliente
    • Suporte a otimização SVG
    • Qualidade e dimensões configuráveis

Versões Atuais

  • @sveltia/cms: 0.113.5 (Outubro de 2025)
  • Status: Beta Público (v1.0 esperada para início de 2026)
  • Maturidade: Pronto para produção (265+ problemas resolvidos do antecessor)

Quando Usar Esta Skill

✅ Use o Sveltia CMS Quando:

  1. Construindo Sites Estáticos

    • Blogs e documentação com Hugo
    • Sites Jekyll e GitHub Pages
    • Projetos 11ty (Eleventy)
    • Sites de marketing com Gatsby
    • Sites com muito conteúdo em Astro
  2. Editores Não Técnicos Precisam de Acesso

    • Equipes de marketing gerenciando páginas
    • Autores escrevendo posts de blog
    • Equipes de conteúdo sem conhecimento de Git
    • Clientes precisando de atualizações fáceis de conteúdo
  3. Fluxo de Trabalho Baseado em Git Desejado

    • Versionamento de conteúdo através do Git
    • Revisão de conteúdo através de pull requests
    • Conteúdo vive com o código no repositório
    • Integração CI/CD para deployments
  4. Solução Leve Necessária

    • Projetos sensíveis a desempenho
    • Edição mobile-first necessária
    • Tempos de carregamento rápidos críticos
    • Tamanho mínimo do bundle importante
  5. Migrando do Decap/Netlify CMS

    • O config.yml existente pode ser reutilizado
    • Substituição direta (alterar 1 linha)
    • Melhor desempenho e UX
    • Manutenção ativa e correções de bugs

❌ Não Use o Sveltia CMS Quando:

  1. Colaboração em Tempo Real Necessária

    • Múltiplos usuários editando simultaneamente (estilo Google Docs)
    • Use Sanity, Contentful ou TinaCMS
  2. Construção Visual de Páginas Necessária

    • Construtores de página por arrastar e soltar necessários
    • Use Webflow, Builder.io ou TinaCMS (React)
  3. Dados Altamente Dinâmicos

    • E-commerce com inventário em tempo real
    • Dashboards ou análises em tempo real
    • Use bancos de dados tradicionais (D1, PostgreSQL)
  4. Edição Visual Específica para React Necessária

    • Edição de componente em contexto
    • Use TinaCMS (focado em React)

Sveltia CMS vs TinaCMS

Use Sveltia para:

  • Hugo, Jekyll, 11ty, Gatsby (SSGs não-React)
  • Experiência tradicional de painel admin CMS
  • Requisitos de bundle leve
  • Projetos agnósticos de framework

Use TinaCMS para:

  • React, Next.js, Astro (componentes React)
  • Edição visual em contexto
  • Conteúdo type-safe orientado por esquema
  • Experiência de desenvolvedor moderna com TypeScript

Ambos são válidos - Sveltia complementa o TinaCMS para diferentes casos de uso.


Padrões de Configuração por Framework

Use o padrão de configuração apropriado com base na sua escolha de framework.

1. Configuração Hugo (Mais Comum)

Hugo é o gerador de site estático mais popular para o Sveltia CMS.

Passos:

  1. Criar diretório admin:

    mkdir -p static/admin
    
  2. Criar página de índice admin:

    <!-- static/admin/index.html -->
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Gerenciador de Conteúdo</title>
      </head>
      <body>
        <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
      </body>
    </html>
    
  3. Criar arquivo de configuração:

    # static/admin/config.yml
    backend:
      name: github
      repo: owner/repo
      branch: main
    
    media_folder: static/images/uploads
    public_folder: /images/uploads
    
    collections:
      - name: posts
        label: Posts do Blog
        folder: content/posts
        create: true
        slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
        fields:
          - { label: 'Título', name: 'title', widget: 'string' }
          - { label: 'Data', name: 'date', widget: 'datetime' }
          - { label: 'Rascunho', name: 'draft', widget: 'boolean', default: true }
          - { label: 'Tags', name: 'tags', widget: 'list', required: false }
          - { label: 'Corpo', name: 'body', widget: 'markdown' }
    
  4. Iniciar servidor de desenvolvimento Hugo:

    hugo server
    
  5. Acessar admin:

    http://localhost:1313/admin/
    

Modelo: Veja templates/hugo/


2. Configuração Jekyll

Jekyll é comumente usado com GitHub Pages e Sveltia CMS.

Passos:

  1. Criar diretório admin:

    mkdir -p admin
    
  2. Criar página de índice admin:

    <!-- admin/index.html -->
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Gerenciador de Conteúdo</title>
      </head>
      <body>
        <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
      </body>
    </html>
    
  3. Criar arquivo de configuração:

    # admin/config.yml
    backend:
      name: github
      repo: owner/repo
      branch: main
    
    media_folder: assets/images/uploads
    public_folder: /assets/images/uploads
    
    collections:
      - name: posts
        label: Posts do Blog
        folder: _posts
        create: true
        slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
        fields:
          - { label: 'Layout', name: 'layout', widget: 'hidden', default: 'post' }
          - { label: 'Título', name: 'title', widget: 'string' }
          - { label: 'Data', name: 'date', widget: 'datetime' }
          - { label: 'Categorias', name: 'categories', widget: 'list', required: false }
          - { label: 'Corpo', name: 'body', widget: 'markdown' }
    
  4. Iniciar servidor de desenvolvimento Jekyll:

    bundle exec jekyll serve
    
  5. Acessar admin:

    http://localhost:4000/admin/
    

Modelo: Veja templates/jekyll/


3. Configuração 11ty (Eleventy)

11ty funciona bem com Sveltia CMS para sites estáticos flexíveis.

Passos:

  1. Criar diretório admin:

    mkdir -p admin
    
  2. Criar página de índice admin:

    <!-- admin/index.html -->
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Gerenciador de Conteúdo</title>
      </head>
      <body>
        <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
      </body>
    </html>
    
  3. Criar arquivo de configuração:

    # admin/config.yml
    backend:
      name: github
      repo: owner/repo
      branch: main
    
    media_folder: src/assets/images
    public_folder: /assets/images
    
    collections:
      - name: blog
        label: Posts do Blog
        folder: src/posts
        create: true
        slug: '{{slug}}'
        fields:
          - { label: 'Título', name: 'title', widget: 'string' }
          - { label: 'Descrição', name: 'description', widget: 'text' }
          - { label: 'Data', name: 'date', widget: 'datetime' }
          - { label: 'Tags', name: 'tags', widget: 'list', required: false }
          - { label: 'Corpo', name: 'body', widget: 'markdown' }
    
  4. Adicionar cópia passthrough ao .eleventy.js:

    module.exports = function(eleventyConfig) {
      eleventyConfig.addPassthroughCopy('admin');
      // ... resto da configuração
    };
    
  5. Iniciar servidor de desenvolvimento 11ty:

    npx @11ty/eleventy --serve
    
  6. Acessar admin:

    http://localhost:8080/admin/
    

Modelo: Veja templates/11ty/


4. Configuração Astro

Astro é um framework moderno que funciona bem com Sveltia CMS.

Passos:

  1. Criar diretório admin:

    mkdir -p public/admin
    
  2. Criar página de índice admin:

    <!-- public/admin/index.html -->
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Gerenciador de Conteúdo</title>
      </head>
      <body>
        <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
      </body>
    </html>
    
  3. Criar arquivo de configuração:

    # public/admin/config.yml
    backend:
      name: github
      repo: owner/repo
      branch: main
    
    media_folder: public/images
    public_folder: /images
    
    collections:
      - name: blog
        label: Posts do Blog
        folder: src/content/blog
        create: true
        slug: '{{slug}}'
        format: mdx
        fields:
          - { label: 'Título', name: 'title', widget: 'string' }
          - { label: 'Descrição', name: 'description', widget: 'text' }
          - { label: 'Data de Publicação', name: 'pubDate', widget: 'datetime' }
          - { label: 'Imagem de Destaque', name: 'heroImage', widget: 'image', required: false }
          - { label: 'Corpo', name: 'body', widget: 'markdown' }
    
  4. Iniciar servidor de desenvolvimento Astro:

    npm run dev
    
  5. Acessar admin:

    http://localhost:4321/admin/
    

Modelo: Veja templates/astro/


5. Configuração Agnóstica de Framework

Aplica-se a: Gatsby, Next.js (modo SSG), SvelteKit, Remix, ou qualquer framework

Passos:

  1. Determinar diretório público:

    • Gatsby: static/
    • Next.js: public/
    • SvelteKit: static/
    • Remix: public/
  2. Criar diretório admin na pasta pública:

    mkdir -p <pasta-publica>/admin
    
  3. Criar página de índice admin:

    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Gerenciador de Conteúdo</title>
      </head>
      <body>
        <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
      </body>
    </html>
    
  4. Criar arquivo de configuração adaptado à sua estrutura de conteúdo:

    backend:
      name: github
      repo: owner/repo
      branch: main
    
    media_folder: <seu-caminho-de-midia>
    public_folder: <seu-caminho-publico>
    
    collections:
      # Defina com base na sua estrutura de conteúdo
    
  5. Acessar admin:

    http://localhost:<porta>/admin/
    

Configuração de Autenticação

Escolha o método de autenticação que se adequa à sua plataforma de implantação.

Opção 1: Cloudflare Workers OAuth (Recomendado) 🔥

Melhor para: Cloudflare Pages, Cloudflare Workers, qualquer implantação

Isso usa o worker oficial sveltia-cms-auth do Cloudflare para OAuth.

Passos:

  1. Implantar Worker:

    # Clone o auth worker
    git clone https://github.com/sveltia/sveltia-cms-auth
    cd sveltia-cms-auth
    
    # Instale dependências
    npm install
    
    # Implante no Cloudflare Workers
    npx wrangler deploy
    

    Ou use implantação com um clique:

  2. Registrar App OAuth no GitHub:

  3. Configurar Variáveis de Ambiente do Worker:

    # Configure credenciais do GitHub
    npx wrangler secret put GITHUB_CLIENT_ID
    # Cole seu Client ID
    
    npx wrangler secret put GITHUB_CLIENT_SECRET
    # Cole seu Client Secret
    
    # Opcional: Restringir a domínios específicos
    npx wrangler secret put ALLOWED_DOMAINS
    # Exemplo: seudominio.com,*.seudominio.com
    
  4. Atualizar configuração do CMS:

    # admin/config.yml
    backend:
      name: github
      repo: owner/repo
      branch: main
      base_url: https://seu-worker.workers.dev  # ← Adicione esta linha
    
  5. Testar autenticação:

    • Abra o /admin/ do seu site
    • Clique em "Login with GitHub"
    • Autorize o app
    • Você deve ser redirecionado de volta ao CMS

Guia completo: Veja references/cloudflare-auth-setup.md

Modelo: Veja templates/cloudflare-workers/


Opção 2: Vercel Serverless Functions

Melhor para: Implantações Vercel

Passos:

  1. Criar rota de API:

    // api/auth.ts
    export default async function handler(req, res) {
      // Lógica de manipulação OAuth
      // Veja templates/vercel-serverless/api-auth.ts
    }
    
  2. Definir variáveis de ambiente na Vercel:

    GITHUB_CLIENT_ID=seu_client_id
    GITHUB_CLIENT_SECRET=seu_client_secret
    
  3. Atualizar configuração do CMS:

    backend:
      name: github
      repo: owner/repo
      branch: main
      base_url: https://seudominio.com/api/auth
    

Opção 3: Netlify Functions

Melhor para: Implantações Netlify

Passos:

  1. Criar função Netlify:

    // netlify/functions/auth.js
    exports.handler = async (event) => {
      // Lógica de manipulação OAuth
      // Veja templates/netlify-functions/auth.js
    };
    
  2. Definir variáveis de ambiente na Netlify:

    GITHUB_CLIENT_ID=seu_client_id
    GITHUB_CLIENT_SECRET=seu_client_secret
    
  3. Atualizar configuração do CMS:

    backend:
      name: github
      repo: owner/repo
      branch: main
      base_url: https://seudominio.com/.netlify/functions/auth
    

Suporte a Múltiplos Backends Git

O Sveltia CMS suporta vários provedores Git. Use a configuração de backend correspondente.

GitHub

backend:
  name: github
  repo: owner/repo
  branch: main
  base_url: https://seu-worker.workers.dev

GitLab

backend:
  name: gitlab
  repo: owner/repo
  branch: main
  app_id: seu_app_id_gitlab
  base_url: https://seudominio.com/api/auth

Gitea / Forgejo

backend:
  name: gitea
  repo: owner/repo
  branch: main
  api_root: https://git.exemplo.com/api/v1
  base_url: https://seudominio.com/api/auth

Configuração de Coleções

Adapte estas configurações de coleção para se adequar à estrutura do seu conteúdo.

Coleção de Blog (Markdown)

collections:
  - name: blog
    label: Blog
    folder: content/blog
    create: true
    delete: true
    slug: '{{slug}}'
    preview_path: blog/{{slug}}
    fields:
      - { label: 'Título', name: 'title', widget: 'string' }
      - { label: 'Data de Publicação', name: 'date', widget: 'datetime' }
      - { label: 'Imagem de Destaque', name: 'image', widget: 'image', required: false }
      - { label: 'Tags', name: 'tags', widget: 'list', required: false }
      - { label: 'Corpo', name: 'body', widget: 'markdown' }

Coleção de Páginas (Markdown)

collections:
  - name: pages
    label: Páginas
    folder: content/pages
    create: true
    delete: true
    slug: '{{slug}}'
    preview_path: '{{slug}}'
    fields:
      - { label: 'Título', name: 'title', widget: 'string' }
      - { label: 'URL Amigável', name: 'slug', widget: 'string', hint: 'O caminho da URL para esta página' }
      - { label: 'Ordem no Menu', name: 'menu_order', widget: 'number', required: false }
      - { label: 'Descrição', name: 'description', widget: 'text', required: false }
      - { label: 'Conteúdo', name: 'body', widget: 'markdown' }

Configuração (JSON/YAML)

collections:
  - name: settings
    label: Configurações
    files:
      - label: Configurações Gerais
        name: general
        file: src/data/settings.json
        format: json
        fields:
          - { label: 'Título do Site', name: 'site_title', widget: 'string' }
          - { label: 'Descrição', name: 'description', widget: 'text' }
          - { label: 'URL Base', name: 'base_url', widget: 'string' }
          - { label: 'Email de Contato', name: 'contact_email', widget: 'string', required: false }

Internacionalização

Configure múltiplos idiomas no Sveltia CMS.

Configuração de Idiomas

i18n:
  structure: multiple_folders  # ou multiple_files, single_file
  locales: [pt, en, es]
  default_locale: pt

Coleção com i18n (Estrutura de Pastas Múltiplas)

collections:
  - name: blog
    label: Blog
    folder: content/blog
    create: true
    i18n: true
    fields:
      - label: Título
        name: title
        widget: string
        i18n: true
      - label: Corpo
        name: body
        widget: markdown
        i18n: true

Integração DeepL

Para habilitar tradução automática via DeepL:

  1. Obter chave de API DeepL em https://www.deepl.com/pro-api
  2. Adicionar ao config.yml:
    i18n:
      deepl_api_key: sua_chave_depl
    

Solução de Problemas

Erros de Autenticação OAuth

Sintoma: Tela de login em branco ou redirecionamento falha

Soluções:

  1. Verifique se base_url corresponde exatamente à URL do seu provedor de autenticação
  2. No GitHub OAuth, verifique se o Authorization callback URL está correto
  3. Confirme que as variáveis de ambiente (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET) estão definidas corretamente
  4. Verifique logs do seu provedor de autenticação para erros
  5. Se estiver usando Cloudflare Workers, execute npx wrangler tail para logs ao vivo

Erros de Parse YAML

Sintoma: "Erro ao parsear arquivo de configuração" ou seção de configuração não carregando

Soluções:

  1. Valide seu YAML com https://www.yamllint.com/
  2. Verifique se a indentação está consistente (use espaços, não tabs)
  3. Certifique-se de que os caminhos folder existam no seu repositório
  4. Verifique se as strings com caracteres especiais estão devidamente escapadas

Exemplo de Config YAML Inválido (Corrigido)

# Inválido: indentação com tab
collections:
	- name: blog

# Válido: indentação com espaços
collections:
  - name: blog

Problemas de Política CORS/COOP

Sintoma: Admin carrega vazio ou console exibe erros de rede

Soluções:

  1. Certifique-se de que seu site serve arquivos estáticos corretamente
  2. Se estiver atrás de um proxy (Nginx, Apache), verifique a configuração de cabeçalhos CORS
  3. Para Cloudflare Pages, verifique as regras de transform HTTP
  4. Adicione cabeçalhos apropriados se necessário:
    Cross-Origin-Opener-Policy: same-origin
    Cross-Origin-Embedder-Policy: require-corp
    

Conteúdo Não Listando

Sintoma: Páginas admin carregam mas nenhum conteúdo é exibido

Soluções:

  1. Verifique se os caminhos da coleção folder correspondem aos diretórios reais
  2. Se estiver usando GitLab/Gitea, certifique-se de que o token de API tenha escopos de repositório
  3. Para repositórios privados, certifique-se de que o app OAuth tenha acesso
  4. Verifique o formato do arquivo: Sveltia CMS espera arquivos .md, .mdx, .yml, .yaml, .json, .toml

Referências

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

Habilidades Relacionadas