Saltar para o conteúdo
duxt

Várias versões

Servir a mesma documentação em várias refs, com seletor e aviso.

Uma ref torna-se uma versão. Aponta uma fonte para tags e cada uma é publicada, com um segmento de versão no URL e uma entrada no seletor.

Passos

  1. Lista as refs. Um texto simples é um ramo. Uma tag tem de o dizer — o git mantém os dois em espaços de nomes separados, e pedir uma tag sob refs/heads faz a compilação falhar.
    sources: [
  {
    repo: 'acme/api',
    path: 'docs',
    refs: [
      { branch: 'main', status: 'upcoming' },
      { tag: 'v2.0.0' },
      { tag: 'v1.4.0' },
      { tag: 'v0.9.0', status: 'eol' }
    ]
  }
],
sourceOptions: { defaultRef: 'v2.0.0' }
  2. Nomeia a predefinida. defaultRef é a ref servida sem prefixo de versão e aquela para onde os motores de busca são apontados. Se não for definida, é a primeira da lista — o que raramente é o que queres quando a lista começa por um ramo.
  3. Declara o ciclo de vida onde não pode ser deduzido. O semver ordena tags, por isso «mais antiga do que a predefinida» não precisa de ajuda. O que não consegue é situar um ramo face a uma tag: main é upcoming, e sem o dizer pede-se ao seu leitor que atualize para uma versão mais antiga do que aquela que está a ler.
  4. Usa latest se não quiseres editar esta lista a cada lançamento. Resolve, na compilação, para a tag semver mais recente desse repositório.
    refs: [{ branch: 'main', status: 'upcoming' }, 'latest']
  5. Assinala o requisito de versão de uma página no texto, onde quem olha para uma versão não consegue ver as outras:
    ### Novas tentativas :since{version="v2.0.0"}

O que acontece às versões antigas

Uma versão não predefinida leva noindex e um canonical a apontar para a mesma página na predefinida, e uma versão eol sai completamente do sitemap. É isso que impede um motor de busca de oferecer v0.9.0 onde o leitor queria a documentação de hoje — ver URL e versões.

Lista de verificação

  • Cada tag está escrita como { tag: … }, não como texto simples
  • defaultRef nomeia a versão onde os leitores devem aterrar
  • Um ramo na lista traz um status explícito
  • O seletor mostra todas as versões, com distintivo nas mortas
  • A página de uma versão morta não está em /sitemap.xml
Esta página foi útil?