Documentação
Começando
Do zero ao seu site rodando no computador, com o painel pronto para preencher. Leva uns 10 minutos, quase todos esperando a instalação. O caminho é o mesmo para um site pessoal (portfólio) e para um site de empresa; só muda o tipo que você escolhe no início. O que muda no site de empresa está em Site de empresa.
Já tem um site feito com o Rubrica v1? Não comece do zero: siga Migrar da v1. Vai continuar na v1 por enquanto? A documentação dela está na branch
v1do GitHub.
O que você precisa
- Node.js 22.23.4 ou mais novo e git. O pnpm é opcional: sem ele, o CLI usa o npm.
- Uma conta no Convex (gratuita). É o backend: guarda o conteúdo, o login e as imagens. Não precisa criar antes: o CLI abre o login no navegador na hora certa.
- Para publicar depois, uma conta na Vercel (gratuita). Veja Publicar o site.
Pagamentos (Asaas), tradução com IA (OpenRouter), avisos no Telegram e por e-mail são opcionais. Dá para ligar cada um depois: veja Integrações.
1. Escolha a aparência no site
No combinador, teste tema, esquema de cores e modo claro ou escuro no site de demonstração funcionando. Depois, na seção Crie o seu, escolha o tipo de site, preencha o nome, o endereço e o e-mail, e copie o comando pronto. Nada do que você digita sai do navegador: o comando é montado na própria página.
Prefere decidir no terminal? Pule para o passo 2 sem as opções: o CLI faz as mesmas perguntas.
2. Crie o projeto
Cole o comando num terminal, na pasta onde quer criar o projeto. Ele tem este formato:
npx create-rubrica@latest ana-souza --tipo pessoal --tema zine --esquema riso --modo claro
Ou rode só npx create-rubrica@latest meu-site e responda às perguntas: tipo de site, tema, nome, endereço, descrição, e-mail, idiomas, esquema de cores, modo e plugins. Todas as opções estão em Comandos do CLI.
O CLI cria a pasta, escreve os arquivos, instala as dependências e inicia o git. Um projeto novo tem pouco código seu: o site vem de dois pacotes, @rubrica/core e o tema escolhido (@rubrica/theme-<nome>).
| Arquivo ou pasta | Para quê |
|---|---|
astro.config.ts |
Configuração do site. Os trechos entre marcadores rubrica: são do CLI |
rubrica.json |
Estado do projeto (tipo, tema, idiomas, plugins). O CLI mantém: não edite à mão |
convex/ |
Backend. Os arquivos de convex/rubrica/ são gerados (uma linha cada) |
src/blocks/ |
Blocos próprios, se você criar |
src/overrides/ |
Componentes ejetados, se você ejetar |
AGENTS.md, .mcp.json |
Instruções e configuração para agentes de IA |
3. Ligue o Convex e crie o seu login
No fim do create, o CLI oferece rodar o setup (ou rode npx create-rubrica setup quando quiser). Ele:
- abre o login do Convex no navegador e cria um deployment de desenvolvimento;
- grava as chaves e variáveis que o backend precisa;
- pede o e-mail e a senha do seu usuário do painel, o
root. A senha é digitada ali, no terminal; - monta as páginas iniciais pela receita do tema (home, sobre, contato e o resto);
- pergunta, uma a uma, as integrações opcionais (Telegram, e-mail, OpenRouter, Asaas, botão Publicar). Pode pular todas.
4. Veja o site
Abra dois terminais na pasta do projeto:
pnpm dev # o site, em http://localhost:4321
pnpm dev:convex # o backend de desenvolvimento
O painel fica em /admin: entre com o e-mail e a senha do passo 3. Preencha a identidade, as páginas e o conteúdo (veja Conteúdo e painel). Para ver o site sem banco nenhum, RUBRICA_FIXTURES=<pasta com site.json e pages.json> pnpm build.
5. Publique
Quando estiver pronto, npx create-rubrica publicar põe o site no ar na Vercel, com um banco de produção separado do seu. Detalhes e outras hospedagens em Publicar o site.
Dois bancos, sempre
O .env.local aponta para o Convex de desenvolvimento, o do seu computador. O site no ar usa o de produção, cujo endereço fica em producao no rubrica.json. Mexer no painel do computador não muda o site publicado. Comandos que publicam (npx convex deploy, publicar) gravam sempre em produção: só rode com a intenção de mudar o site no ar.
Próximos passos
- Conteúdo e painel: páginas com blocos, coleções e papéis
- Temas: trocar o tema, as cores e as fontes
- Idiomas: mais de um idioma
- Agentes: editar o conteúdo com o Claude Code ou o Codex