Secções geradas

Uma fonte publica o Markdown que um repositório guarda. Uma secção gerada publica algo que não é Markdown de todo: uma fonte nomeia um artefacto e o tipo que o lê, e as páginas seguem daí.

{
  path: 'docs',
  generated: [
    { type: 'changelog', path: 'CHANGELOG.md', label: 'Releases' },
    { type: 'openapi', path: 'openapi.yaml', label: 'API' },
    { type: 'bruno', path: 'bruno', label: 'Requests' }
  ]
}

A camada traz três tipos gerados — changelog, openapi e bruno — e o registo está aberto, portanto um site pode acrescentar os seus ou substituir um. Os campos estão em Fontes.

tfplugindocs está relacionado, mas não é deliberadamente um quarto tipo gerado: é um dialeto de fonte para uma árvore Markdown que já existe. Os tipos gerados transformam outro artefacto em páginas Markdown; um dialeto ensina ao duxt a estrutura do Markdown existente.

#As páginas são uma coleção comum

É este o ponto todo, e vale a pena dizê-lo com clareza: o que um tipo produz são ficheiros Markdown, escritos numa coleção que o Content constrói como qualquer outra. Por isso a pesquisa encontra-as, o llms.txt lista-as, o sitemap leva-as, o seletor de versões move-se entre elas, e o botão de cópia entrega a página a um modelo.

Nada aqui é um segundo caminho de renderização. Um tipo que tivesse de se ensinar à pesquisa, ou ao feed, ou ao sitemap, seria um site paralelo dentro do site — e cada uma dessas costuras é um sítio por onde as duas metades se afastam.

#O que pertence a um tipo, e o que não

Um tipo responde a três perguntas e nada mais: como dividir o seu artefacto em páginas, e as duas políticas abaixo. Não decide para onde vai a sua entrada na barra, como se chama a secção, nem que artefacto lê — isso pertence à declaração, porque pertence ao site.

#Versionamento

Uma descrição de API pertence à versão que descreve: a um leitor em v1 que pergunta o que significa um campo não pode mostrar-se a resposta de v2. Um registo de alterações é por versão pela mesma razão — cada versão entregou o seu próprio CHANGELOG.md, e quem muda de versão fica no registo de alterações em vez de ser mandado para uma visão geral. global fica para um tipo cujo artefacto é de facto um único histórico num URL neutro quanto à versão.

Que o mesmo mecanismo produza ambos é a razão pela qual o versionamento é uma política do tipo e não uma regra da camada.

#Localização

Um tipo per-locale lê o mapa locales da declaração — um artefacto por idioma, porque uma descrição OpenAPI traduzida é um artefacto a sério e não o mesmo ficheiro reetiquetado. Um idioma que o mapa não nomeia não constrói nada, e é deliberado: a cadeia de recurso existente serve-lhe então o idioma predefinido e o aviso de tradução di-lo. Declarar um artefacto para cada idioma e servir em silêncio o mesmo ficheiro sob cada um deixaria esse aviso mudo e o leitor sem saber.

Um tipo original salta o mapa por completo. Um registo de versões escreve-se uma vez, pela ferramenta de release, no idioma em que o projeto faz commits — um site localizado serve portanto o original e di-lo com o aviso que já desenha.

#Onde falham

Um artefacto local em falta, ilegível, ou a que se passa uma opção que o seu tipo não conhece faz a compilação falhar enquanto a configuração é carregada: a configuração própria do site é um erro que a compilação não deve carregar, e uma secção que ficou vazia em silêncio é uma secção cuja ausência ninguém nota.

O que sobra é ou um artefacto remoto, que pode legitimamente ter envelhecido entre uma versão e a seguinte, ou uma página que renderizou com algo em falta. Isso são avisos no relatório de compilação — ver O que a compilação verifica.