Configuração

Tudo o que se segue vive sob duxt no teu app/app.config.ts. Como a combinação funciona, e porque os arrays substituem em vez de acrescentar, está em Configuração.

#Site

#Comportamento

export default defineAppConfig({
  duxt: {
    copy: {
      models: [
        {
          label: 'O meu assistente',
          icon: 'simple-icons:openai',
          url: 'https://example.com/new?prompt='
        }
      ]
    },
    contributors: {
      avatarUrl: 'https://github.com/{username}.png?size=96'
    },
    toc: { depth: 4, scrollOffset: 112 },
    search: {
      fuzzy: { threshold: 0.3, minMatchCharLength: 3, limit: 15 },
      recentPages: 8
    },
    openapi: { exampleDepth: 6, schemaDepth: 8 },
    shortcuts: { singleCharacter: false }
  }
})

As listas substituem os padrões. Uma lista copy.models vazia remove destinos externos, não as ações de copiar e ver a fonte. search.recentPages: 0 não guarda entradas novas. As opções fuzzy só afetam aproximações depois de uma pesquisa Content vazia. Sem callback de analytics nada é enviado; consentimento, provider e armazenamento pertencem ao site consumidor.

#logo

Definir um é Dá identidade ao teu site.

#organization

O nó Organization que os motores de busca e os resumos de IA leem para nomear uma fonte. Ausente até o definires: o duxt renderiza a documentação de outros e não adivinha de quem.

#Anúncios

Um aviso para todo o site — uma versão, uma migração ou uma manutenção. Nada é renderizado nem ocupa espaço até escreveres uma entrada.

announcements: [
  {
    text: { 'en-GB': 'Version 2 is out.', 'pt-PT': 'A versão 2 foi lançada.' },
    link: { label: 'Ler as notas', to: '/releases/v2' }
  },
  {
    id: 'march-maintenance',
    text: 'Manutenção agendada no domingo a partir das 09:00 UTC.',
    placement: 'below-header',
    startsAt: '2026-03-01T09:00:00Z',
    endsAt: '2026-03-08T09:00:00Z'
  }
],
announcementOptions: { maxVisible: 1 }

A lista é desenhada por ordem: uma versão e uma indisponibilidade são dois anúncios, e o fim de um não deve retirar o outro.

#Onde são apresentados

above-content pertence à coluna do documento, por isso aparece em páginas de documentação e não numa landing page sem essa coluna.

announcementOptions.maxVisible limita quantos anúncios uma posição mostra ao mesmo tempo. Um número limita cada posição, um objeto limita-as separadamente ({ 'above-header': 1 }), e null, uma chave omitida ou a ausência de maxVisible significa ilimitado. Fechar o aviso superior promove o seguinte.

#Quando são apresentados

startsAt e endsAt são lidos no browser contra o relógio do leitor. O anúncio começa e termina sem deploy nem recarregar a página. A janela é semiaberta: visível desde startsAt e até endsAt.

Escreve um offset quando o instante exato importa (2026-03-01T09:00:00Z). Sem fuso horário usa-se a hora local do leitor. Uma data inválida é tratada como ausente, para que um erro não esconda o aviso em silêncio.

#Fecho

Um anúncio fechado permanece fechado durante navegação, reloads e mudanças de idioma. É a sua identidade que fica guardada:

• com id, exatamente essa string independente do locale; mudá-la volta a mostrar o anúncio a todos,
• sem id, um valor derivado de todas as variantes de text e link; mudar o texto cria um anúncio novo, reordenar as chaves de locale não.

Define id para corrigir o texto sem voltar a apresentá-lo. Os fechos vivem apenas em localStorage; chaves de anúncios removidos são descartadas. Como o relógio e os fechos pertencem ao browser, a faixa é desenhada depois da hidratação.

A superfície do componente está em DuxtAnnouncements.

#Navegação e ligações

Uma entrada de secção é uma ligação mais um campo próprio:

Útil onde as páginas não podem levar ícone — o frontmatter de um ADR está fixo em title, description, status e date, pelo que o registo de decisões seria apresentado sem nenhum.

A maioria é entregue vazia, por duas razões diferentes. links, aside.links, footer.legal, title, version e o texto da página inicial nomeiam um projeto concreto — um repositório, uma comunidade, um aviso legal, um nome, uma versão publicada, uma frase sobre o que faz — e pertencem a quem gere o site. sections nomeia as partes de uma árvore de documentação, e a árvore é tua: quatro separadores a apontar para nomes de pasta que a camada adivinhasse não levariam a lado nenhum. Define-o quando a tua documentação tiver secções; até lá a linha não é apresentada e a barra lateral mostra a árvore inteira, que é a forma certa para documentação sem secções.

Uma linha por fonte. Uma entrada pertence à fonte sob cujo prefixo de URL está, e a linha mostra as entradas da fonte em que o leitor se encontra — um site com a documentação na raiz e outra coisa em /demo escreve assim uma só lista sections, e cada área desenha a sua parte dela. Uma secção gerada por baixo de uma área (/demo/openapi) pertence a essa área em vez de ser uma. Um site com uma única fonte tem uma área, cada entrada está lá dentro, e a linha é exactamente a lista tal como foi escrita.

#A página inicial

A página em / desenha três faixas, e cada uma está ausente até a sua chave estar definida.

command é uma string simples, não texto: um comando de shell é igual em todos os idiomas, e um traduzido por engano é um que não corre. A camada não entrega nenhum — não sabe como se chama o teu projeto, pela mesma razão por que links está vazio.

Não há chamada à ação final, deliberadamente. Os botões do bloco principal são a chamada; repeti-los sob uma grelha de cartões pede a um leitor acabado de chegar que decida duas vezes.

badge é entregue vazio pela mesma razão que links: uma pastilha por cima do título diz algo sobre o estado de um projeto — «beta», «a v2 saiu» — e a camada nada sabe sobre o estado do teu. Um texto é a forma curta; o objeto acrescenta ícone, cor e destino.

badge: {
  label: '{version} lançada',
  icon: 'lucide:rocket',
  variant: 'success',
  to: 'https://github.com/acme/sdk/releases/latest',
  external: true
}

preview é uma janela viva, não uma imagem. Incorpora uma página deste site num enquadramento de browser que o leitor pode percorrer, navegar e cujo tema pode mudar sem sair da página inicial. O enquadramento só é montado quando a faixa entra no ecrã, e nunca durante a renderização no servidor — um iframe no HTML inicial é um segundo carregamento completo a competir com o primeiro.

#Forma de uma ligação

Todos os campos marcados como texto aceitam um literal, uma chave i18n ou um registo por locale — ver Localização.

#Fontes

Ambas as chaves de fonte têm uma página própria. locales é a terceira chave de compilação: alterar qualquer uma das três exige nova compilação.

#O feed

/rss.xml está vazio até feed.path nomear uma secção:

feed: { path: '/changelog', title: 'o meu projeto — lançamentos' }

Desligado por omissão, de propósito. Um feed é uma lista de coisas que aconteceram, e uma página de referência editada não é um acontecimento — um site que publica cada edição como item ensina os seus leitores a cancelar a subscrição. Os itens são ordenados pela date da própria página, recorrendo ao último commit que lhe tocou, e só a versão predefinida de cada fonte contribui, por isso um changelog versionado não repete cada entrada uma vez por versão.

A secção para a qual costuma apontar é um histórico de versões, cujas páginas trazem cada uma a sua date.

#Gerado, não escrito

Definir qualquer um dos três à mão é sobrescrito na compilação seguinte.