Declarar a secção

Um histórico de versões é uma secção gerada: uma fonte nomeia o ficheiro e o tipo que o lê, e as páginas seguem daí.

export default defineAppConfig({
  duxt: {
    sources: [
      {
        path: 'docs',
        generated: [
          {
            type: 'changelog',
            path: 'CHANGELOG.md',
            label: 'Releases'
          }
        ]
      }
    ]
  }
})

Os campos que uma declaração aceita são os mesmos para qualquer tipo e estão em Fontes. changelog nomeia uma opção própria — granularity — e responde às duas políticas abaixo.

#Versionamento

Global. Um histórico, lido da versão predefinida, servido num URL neutro quanto à versão, com o seletor suprimido.

Um registo de alterações não é um documento por versão que menciona outras versões — é a lista das versões. 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, e a um leitor que calhasse de aterrar em v1 dir-se-ia que o projeto parou aí.

#Localização

O original, em todos os idiomas. Uma coleção, construída a partir do idioma predefinido.

Um registo de versões escreve-se uma vez, pela ferramenta de release, no idioma em que o projeto faz commits. Nada nele é por idioma, portanto um site localizado serve o original e di-lo com o aviso de tradução que já desenha para uma página não traduzida. O mapa locales da declaração só é lido por tipos per-locale e aqui não faz nada.

#Para onde vai a entrada

navigation: 'sections' é a predefinição e coloca a entrada na fila das secções — as partes de primeiro nível da documentação.

Um registo de versões muitas vezes não é uma delas: é algo que o projeto tem ao lado da sua documentação, não uma parte dela. navigation: 'navigation' move a entrada para a primeira fila, estreita, e false não a coloca em lado nenhum e deixa o site ligá-la.

{
  type: 'changelog',
  path: 'CHANGELOG.md',
  label: 'Releases',
  navigation: 'navigation'
}

#O feed

duxt.feed.path nomeia a secção a partir da qual o /rss.xml é construído, e um histórico de versões é aquilo para que foi escrito: cada página de versão traz a date própria dessa versão, e uma versão é algo que aconteceu — o que uma página de referência editada não é.

feed: { path: '/releases', title: 'o meu projeto — versões' }

Desligado enquanto a chave não estiver posta. Só a versão predefinida de cada fonte contribui, portanto um site versionado não repete cada entrada uma vez por versão — e com uma secção global há de qualquer modo apenas um histórico. Ver Configuração e /rss.xml.

#Quando o ficheiro não pode ser lido

Um ficheiro local que não está lá faz a compilação falhar enquanto a configuração é carregada, como para qualquer tipo. O que o ficheiro não diz bem — um título que parece uma versão mas não é lido como tal — é em vez disso um aviso no relatório de compilação; ver O que é lido e O que a compilação verifica.