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

#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.

#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/api) 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.