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

Por versão. Cada versão publicada da documentação tem o seu próprio registo de alterações, lido do CHANGELOG.md dessa versão e servido dentro dela — /releases para a versão predefinida, /v2.x/releases ao lado de /v2.x/guides. Funciona exatamente como a documentação e a referência da API ao lado.

Cada cópia mostra o ficheiro inteiro que essa versão entregou, versões anteriores incluídas, pelo que o registo de uma versão mais antiga termina onde essa versão terminou. O seletor de versões mantém o leitor no registo de alterações: numa página de versão abre a mesma versão na outra, e onde essa outra nunca a teve abre a visão geral do seu registo em vez de uma página em falta.

O ficheiro é obrigatório em cada versão. Uma versão publicada sem CHANGELOG.md faz a build falhar, tanto para uma fonte descarregada como para o repositório que se constrói — omitir a versão ou mostrar lá o histórico de outra publicaria em ambos os casos algo que essa versão nunca entregou.

#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 — mesmo que cada versão publique o seu próprio registo de alterações. 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.