URL y versiones

Cada página se sirve en

/[repo]/[version]/[...ruta]

con ambos prefijos opcionales — y la decisión de si cada uno aparece se toma en tiempo de compilación a partir de la lista de fuentes, nunca por petición.

• Un segmento de repositorio aparece en cuanto hay más de un repositorio, o cuando showRepo lo fuerza o — solo para esa fuente — cuando la fuente declara su propio slug.
• Un segmento de versión aparece en cuanto una fuente publica más de una ref, o cuando showVersion lo fuerza.

Así, una sola carpeta sin versiones sirve /guides/deploying, y nada en la URL delata que existan repositorios o versiones.

#Por qué los prefijos se deciden al compilar

Si ambos prefijos fueran opcionales por petición, el primer segmento sería ambiguo: /guides/… podría ser una carpeta, un repositorio o una versión, y solo consultando los tres se sabría cuál. Como la forma de una URL queda fijada antes de la primera petición, el enrutador nunca tiene que adivinar.

Lo que queda es una colisión de nombres mientras un prefijo está activo: una carpeta de documentación llamada como un repositorio o una versión. La compilación la rechaza en lugar de resolverla en silencio hacia un lado; véase Qué comprueba la compilación.

#La versión por defecto

Una ref por repositorio se sirve sin prefijo de versión: la primera de la lista, o la que nombre sourceOptions.defaultRef. Esa es la URL a la que enlazar y a la que se dirige a los buscadores.

#Dónde está una versión en su vida

status en una fuente o una ref es un ciclo de vida, no un sinónimo de «es la predeterminada»: un sitio puede publicar v2 como actual mientras v1 es simplemente más antigua y v0 está realmente muerta, y hay que decirle al lector en cuál de las tres se encuentra.

upcoming es el único que no trata de la edad. Una versión puede no ser la predeterminada porque todavía no ha ocurrido, y decirle a ese lector que «actualice» es exactamente al revés. Semver no puede situar una rama frente a una etiqueta, así que este caso se declara en la configuración en lugar de deducirse.

Junto al aviso, una página de una versión no predeterminada lleva noindex y un canonical que apunta a la misma página en la versión predeterminada — de otro modo, un buscador serviría v0.7.0 con la misma probabilidad que la documentación de hoy. Las dos mitades van juntas: el aviso es la visible, el link-rel la invisible, y cualquiera de ellas por separado deja a un público equivocado.

#Cuando falta una página en una versión

El selector solo ofrece una versión que realmente tenga la página, y el enlace canónico resuelve a la ruta existente más cercana. Una URL que no resuelve a nada se responde con un 404 que sugiere la página más próxima de la navegación — las URL versionadas se fallan fácilmente por un segmento, y un 404 vacío deja al lector sin nada que pulsar.