Um site duxt é uma aplicação Nuxt. Tudo o que corre Nuxt corre-o.

## Passos

:::steps
1. **Prefere estático.** `nuxt generate` produz uma pasta de HTML — sem
   servidor, sem custo de execução, cada página em cache na periferia. É a
   escolha certa por omissão para documentação.

   ::package-managers{command="run generate"}
   ::

   `nuxt build` produz um servidor Node, de que só precisas se uma página tiver
   de reagir a um pedido.

2. **Dá à compilação o que ela precisa.** Node 24 (a base de dados é lida
   através de `node:sqlite`, por isso não se instala nenhum controlador nativo),
   acesso de rede a qualquer fonte remota, e um token para as privadas.

3. **Define a origem.** `NUXT_PUBLIC_I18N_BASE_URL`, ou `i18n.baseUrl` na
   configuração. Sem ela, `hreflang`, `canonical`, o sitemap e os cartões
   sociais recaem em saída relativa.

4. **Define um segredo de imagem OG se implementares mais do que uma
   instância.** `NUXT_OG_IMAGE_SECRET`, gerado uma vez. Sem ele cada compilação
   assina os URL de imagem com um segredo próprio, e um cartão assinado por uma
   instância é rejeitado pela seguinte.

5. **Agenda uma nova compilação.** Um site que lê outro repositório recolhe as
   alterações quando compila, não quando são enviadas.

:::

## Porque não há atualização em execução

O Content descarrega um repositório remoto na compilação e compila-o na base de
dados que a compilação entrega. Atualizar isso em execução significaria
reconstruir a base de dados dentro de um servidor vivo — o Content não oferece
nenhum caminho suportado para isso, e o único disponível é a mesma base de dados
de cliente que a pesquisa lê. Uma nova compilação agendada, ou desencadeada a
partir do repositório de origem, mantém a implementação imutável e o conteúdo
reproduzível.

## Quando uma compilação diz `database is locked`

O Content guarda a sua cache de análise em `.data/content/contents.sqlite`, e
uma compilação que o kernel ou um `Ctrl-C` deixou para trás pode continuar a
mantê-la aberta. Cada compilação seguinte falha então com `database is locked` —
uma mensagem que não nomeia nem o ficheiro nem o processo.

O duxt coloca essa base de dados em [modo WAL](https://www.sqlite.org/wal.html)
antes de o Content a abrir, o que permite que um leitor e um escritor coexistam
e elimina por completo a versão quotidiana disto. O que não consegue eliminar é
um segundo processo ainda em execução:

```bash
pgrep -af 'nuxt (build|dev|generate)'   # o processo órfão, se existir
kill <pid>
```

Se nada aparecer e o erro persistir, apaga `.data/content/` — é uma cache, e a
compilação seguinte reconstrói-a a partir das fontes.

## O que o site serve além das páginas

`/llms.txt`, `/llms-full.txt`, o código `.md` de qualquer página, `/mcp`,
`/sitemap.xml`, `/robots.txt` e — depois de configurado — `/rss.xml`. A lista
completa com as suas ressalvas está na
[referência de endpoints](/reference/endpoints).

## Lista de verificação

- [ ] `nuxt generate` termina sem erro do validador
- [ ] A origem está definida na implementação, não apenas localmente
- [ ] `/sitemap.xml` lista URL absolutos no domínio real
- [ ] Está agendada uma nova compilação, ou é desencadeada a partir de cada
      repositório de origem
- [ ] `NUXT_OG_IMAGE_SECRET` está definido se mais do que uma instância servir o
      site