Granularidade

granularity é a única opção que o tipo lê. Aceita split — a predefinição — ou flat, e a diferença vai mais longe do que o número de páginas.

{
  type: 'changelog',
  path: 'CHANGELOG.md',
  label: 'Changelog',
  options: { granularity: 'flat' }
}

#split — uma página por versão

A predefinição, e aquilo para que serve um histórico de versões. Cada versão passa a ser uma página própria sob uma vista geral gerada, o que compra quatro coisas que uma página só não pode ter:

• uma ligação direta a uma versão, e a um grupo dentro dela;
• um resultado de pesquisa que é a versão, e não o ficheiro inteiro;
• uma entrada de feed por versão, assim que feed.path nomear a secção;
• uma entrada de llms.txt por versão, para que um modelo que pergunte o que mudou em 2.1.0 receba essa versão e não quatrocentos kilobytes de histórico.

A vista geral é uma cronologia — cada versão, a mais recente primeiro, com a sua data e os tipos de alteração ao lado, filtrável por esses tipos. As entradas em si ficam nas páginas de versão: repeti-las na vista geral meteria o registo inteiro duas vezes no índice de pesquisa, no llms-full.txt e no feed.

As páginas separadas renderizam num esquema próprio: as versões na barra lateral, uma coluna de leitura limitada a uma medida, e uma coluna de conteúdos que lista os grupos. Ver Componentes.

#flat — o ficheiro tal como está

Uma página, que contém o ficheiro tal como foi escrito. Para um projeto que apenas quer o seu registo mostrado.

Um registo plano é uma página de documentação comum e mantém o enquadramento da documentação — a barra lateral de prosa, a navegação estrutural e um índice que lista as versões, que é exatamente o que um ficheiro longo quer. É por isso que a questão do esquema é respondida a partir das opções da própria declaração em vez de fixada pelo tipo: o mesmo tipo produz duas coisas diferentes.

Nada é reescrito além do título. O # Changelog próprio do ficheiro sai, porque a página tira o seu título de title e um segundo <h1> no corpo é ao mesmo tempo um duplicado e um achado de acessibilidade. Cada título de versão fica exatamente onde a ferramenta de release o pôs — que é o que «inalterado» tem de querer dizer, ou o modo não é a saída de emergência para que existe.

#A qual recorrer