Keystatic: o CMS que grava o conteúdo no Git

Este blog tem 426 posts e nenhum banco de dados. Cada texto é um arquivo .mdoc numa pasta do repositório. O painel onde eu edito título, data, categoria e corpo do post é o Keystatic, que lê e grava esses arquivos.

Quem vem do WordPress costuma perguntar onde o conteúdo fica guardado. Fica no mesmo lugar do código, com histórico de cada vírgula alterada e de quem alterou.

Essa escolha tem custo e tem limite. Ela funciona muito bem num tipo de site e atrapalha bastante em outro.

Um CMS no Git troca o banco de dados pela revisão de código. Para site de conteúdo com equipe pequena, a troca compensa. Para portal com 30 editores e fluxo de aprovação, ela vira gargalo.

O que é o Keystatic e de onde ele vem

O site oficial do Keystatic se apresenta como gestão de conteúdo para a sua base de código. A descrição é literal: a ferramenta pega arquivos Markdown, JSON e YAML que já estão no projeto e torna esses arquivos editáveis por gente que não abre editor de código. A página também lista suporte a Markdoc e MDX e coloca "No database" entre os recursos.

O projeto é da Thinkmill, uma empresa de software, e nasceu como trabalho de pesquisa da Thinkmill Labs. O código fica no repositório público no GitHub, sob licença MIT. A MIT deixa usar, alterar e até vender o software, desde que o aviso de copyright acompanhe o código, e o post sobre licença open source explica a diferença para as licenças mais restritivas. A CLI cria projetos novos para Next.js, Astro ou Remix.

O funcionamento parte de um arquivo de configuração em TypeScript. Nele você declara as coleções (posts, páginas, autores) e os campos de cada uma: texto, data, seleção, imagem, corpo em Markdoc. O painel, que abre na rota /keystatic, monta o formulário a partir desse schema. Quando você salva, ele escreve o arquivo no caminho que a coleção indica.

Se o conceito de CMS ainda está nebuloso, o post sobre o que é CMS cobre a base. Aqui o ponto é outro: onde o conteúdo mora.

Os três modos de armazenamento

A ferramenta tem três formas de guardar o que você edita, e a escolha muda quem consegue editar.

Modo local. A documentação resume em uma frase: o conteúdo fica direto no sistema de arquivos local. Projetos criados pela CLI começam nesse modo, e a própria doc diz que ele faz mais sentido no início do projeto. Você edita no painel e depois faz o commit como faria com qualquer arquivo.

Modo github. Aqui o painel conversa com o repositório remoto. Na primeira visita a /keystatic, o assistente pede para criar um GitHub App e dar acesso dele ao repositório. O setup gera um .env com client ID, client secret e uma chave secreta. Quem edita entra com a conta do GitHub e precisa ter acesso de escrita ao repositório. O painel ganha um seletor de branch, e a opção branchPrefix limita quais branches aparecem. A documentação do modo github lembra um requisito que pesa: o host precisa rodar Node.js para as rotas de API.

Keystatic Cloud. É um serviço hospedado da própria Thinkmill. Ele resolve a autenticação com o GitHub sem que você crie um app próprio, e permite que membros do time editem sem ter conta no GitHub. Segundo a página do Cloud, a conta é grátis com times e projetos ilimitados, até 3 usuários por time. O plano Pro começa em US$ 10 por mês, cada usuário além do terceiro custa US$ 5 por mês, e ele libera edição simultânea (ainda experimental) e o Cloud Images, um serviço de imagens fora do repositório.

Como este blog usa o Keystatic

O Atraca roda em Astro, e o conteúdo é Markdoc versionado. A configuração usa storage: { kind: "local" }. Uma coleção chamada blog aponta para src/content/blog/* e declara os campos que você vê no topo de qualquer post: título, descrição, idioma, data, categorias, tags, imagem e corpo.

Escolhi não publicar o painel. A integração só entra no build quando uma variável de ambiente liga o editor, e isso acontece na minha máquina. O site que vai para o ar é estático, sem rota /keystatic e sem servidor Node.js em produção.

Esse arranjo evita uma exigência da documentação de instalação para Astro: como o painel roda código no servidor e usa APIs do Node.js, você precisa de um adapter do Astro para fazer o deploy dele. Sem painel em produção, não há adapter para manter.

O fluxo diário é curto. Edito no painel, confiro o git diff, faço o commit e o build gera as páginas. Se um campo do frontmatter quebra, o build falha antes de qualquer coisa ir para o ar.

Keystatic, WordPress e CMS headless: o que muda em cada um

A comparação que interessa olha para onde o conteúdo vive e para quem consegue mexer nele.

O WordPress ganha em tudo que envolve muita gente e muito plugin, e o post sobre as vantagens do WordPress mostra por quê. O headless SaaS ganha quando o mesmo conteúdo alimenta site, aplicativo e outros canais. O CMS em arquivo ganha quando o site é um só e a equipe que edita é a mesma que cuida do código.

Onde o Git ajuda e onde atrapalha

O histórico é o ganho mais visível. Cada alteração tem autor, data e diff. Desfazer um erro é reverter um commit. Backup é um clone do repositório.

Conteúdo e código também mudam juntos. Se eu crio um campo novo no schema e preciso preencher esse campo em 400 arquivos, um script faz isso e o resultado entra num único commit revisável. Num banco, a mesma operação exige migração e acesso ao servidor.

Há ainda o desempenho: sem banco, o site sai do build como HTML estático, e isso facilita o trabalho de otimizar as Core Web Vitals.

Os problemas aparecem quando a equipe cresce. Dois editores mexendo no mesmo arquivo geram conflito de merge, e conflito de merge não é algo que um redator resolve sozinho. Não existe agendamento nativo de publicação nem aprovação por papel, como editor, revisor e publicador. Cada publicação espera um build terminar antes de chegar ao leitor.

Imagem também pesa. Fotos guardadas no repositório incham o histórico para sempre. A Thinkmill oferece o Cloud Images justamente para servir imagens otimizadas sem lotar o repositório no GitHub, segundo a própria documentação.

Como decidir se o Keystatic serve ao seu site

Antes de migrar, passe por estes pontos:

1. Conte quem edita. Até poucas pessoas, todas confortáveis com o repositório ou com o painel, o modelo funciona. Com dezenas de editores e aprovação em etapas, fique no WordPress ou num headless SaaS.
2. Veja como o site é publicado. Site estático com build a cada commit combina com conteúdo em arquivo. Se o deploy hoje é FTP manual, resolva isso primeiro.
3. Comece no modo local. Configure o schema, edite alguns posts e veja o diff. Se ninguém além de você vai editar, talvez nem precise sair desse modo.
4. Mantenha o schema enxuto. Cada campo é uma linha no frontmatter de todos os arquivos. Campo opcional que ninguém usa vira ruído no diff.
5. Decida onde ficam as imagens antes de subir as primeiras centenas. Mudar depois exige reescrever caminhos em todos os posts.
6. Feche a rota do painel em produção se não for usar. A documentação tem uma receita para desativar as rotas do Admin UI no ambiente publicado.
7. Aprenda a ler o repositório. Quem entende commits e branches resolve metade dos problemas sozinho, e o guia de como entender um repositório do GitHub ajuda quem está começando.

O que fica de fora

Um CMS em arquivo não tem busca de conteúdo entre milhares de itens com filtros, não tem permissão por seção e não tem trilha de aprovação. Um blog com dois autores vive bem sem esses recursos, enquanto um portal de notícias sente a falta deles na primeira semana.

Em troca, toda mudança fica registrada no histórico do repositório. O commit deste post vai mostrar um arquivo novo em src/content/blog e nenhuma tabela alterada em lugar nenhum.