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' }
  ]
}

A camada traz dois tipos — changelog e openapi — e o registo está aberto, portanto um site pode acrescentar os seus ou substituir um destes. Os campos que uma declaração aceita são os mesmos para qualquer tipo e estão em Fontes.

#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

Os dois são opostos, e ambos estão certos. 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 é o inverso — não é um documento por versão que menciona outras versões, é a lista das versões, e construir uma cópia por versão publicaria o mesmo ficheiro sob três URL, faltando a cada uma as versões que vieram depois.

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.