URL e versões

Cada página é servida em

/[repo]/[version]/[...caminho]

com ambos os prefixos opcionais — e a decisão sobre se cada um aparece é tomada em tempo de compilação a partir da lista de fontes, nunca por pedido.

• Um segmento de repositório aparece assim que há mais do que um repositório, ou quando showRepo o força ou — só para essa fonte — quando a fonte declara um slug próprio.
• Um segmento de versão aparece assim que uma fonte publica mais do que uma ref, ou quando showVersion o força.

Assim, uma única pasta sem versões serve /guides/deploying, e nada no URL denuncia que repositórios e versões sequer existem.

#Porque os prefixos são decididos na compilação

Se ambos os prefixos fossem opcionais por pedido, o primeiro segmento seria ambíguo: /guides/… podia ser uma pasta, um repositório ou uma versão, e só consultando os três se saberia qual. Como a forma de um URL fica fixada antes do primeiro pedido, o router nunca tem de adivinhar.

O que resta é uma colisão de nomes enquanto um prefixo está ativo: uma pasta de documentação com o nome de um repositório ou de uma versão. A compilação rejeita-a em vez de a resolver em silêncio para um dos lados; ver O que a compilação verifica.

#A versão por omissão

Uma ref por repositório é servida sem prefixo de versão: a primeira da lista, ou a que sourceOptions.defaultRef nomear. É esse o URL a que se deve ligar e para o qual os motores de busca são apontados.

#Onde está uma versão na sua vida

status, numa fonte ou numa ref, é um ciclo de vida e não um sinónimo de «é a predefinida»: um site pode publicar a v2 como atual enquanto a v1 é apenas mais antiga e a v0 está mesmo morta, e é preciso dizer ao leitor em qual dos três está.

upcoming é o único que não é sobre idade. Uma versão pode não ser a predefinida por ainda não ter acontecido, e dizer a esse leitor para «atualizar» é exatamente ao contrário. O semver não consegue situar um ramo face a uma tag, por isso este caso é declarado na configuração em vez de deduzido.

Ao lado do aviso, uma página numa versão não predefinida leva noindex e um canonical a apontar para a mesma página na versão predefinida — caso contrário, um motor de busca serviria a v0.7.0 com a mesma probabilidade que a documentação de hoje. As duas metades andam juntas: o aviso é a visível, o link-rel a invisível, e qualquer uma sozinha deixa um público enganado.

#Quando uma página falta numa versão

O seletor só oferece uma versão que tenha mesmo a página, e a ligação canónica resolve para o caminho existente mais próximo. Um URL que não resolve para nada é respondido com um 404 que sugere a página mais próxima na navegação — é fácil falhar um URL versionado por um segmento, e um 404 vazio deixa o leitor sem nada para clicar.