Versionado

Publica documentación de más de un lanzamiento a la vez - crea una instantánea de versión, y cada tema obtiene un selector de versión gratis.

Versionado

La documentación versionada es convención antes que configuración - no hay ninguna clave de bxsites.json que activar. Añade una carpeta docs/versions/, y cada subcarpeta directa dentro de ella se construye como su propio árbol de documentación totalmente autocontenido, junto a tu docs/ regular (que siempre se construye como "Latest"):

docs/
├── index.md
├── guides/
└── versions/
    ├── 1.0/
    │   ├── index.md
    │   └── guides/
    └── 2.0/
        ├── index.md
        └── guides/

Cada carpeta de versión es un árbol normal con la forma de docs/ - su propio index.md, su propia nav, sus propias páginas - construido en site/versions/<name>/ con cada enlace interno prefijado correspondientemente, y compartiendo la única configuración/tema de bxsites.json del proyecto. Un archivo suelto colocado directamente bajo docs/versions/ (no dentro de una subcarpeta) se ignora.

Crear una nueva versión

version:new toma una instantánea del árbol actual de docs/ en docs/versions/<name>/ - el flujo de trabajo habitual es: termina la documentación de un lanzamiento, crea una versión justo antes de empezar a escribir la documentación del siguiente, de modo que la instantánea congela exactamente lo que se publicó:

bxSites version:new --name=1.0

• --name (obligatorio) - la carpeta/etiqueta de la versión, por ejemplo 1.0

La instantánea excluye assets/, versions/, i18n/ y blog/ - cada una de ellas es su propio árbol cargado por separado, no parte del propio contenido de una versión, así que nunca se duplican dentro de ella.

No hay ningún verbo equivalente para "deshacer una versión" y ningún otro verbo apunta a una versión específica - page:new/page:rename/post:new/etc. siempre operan contra el árbol principal docs/. Editar las propias páginas de una versión ya creada (corregir una errata en docs/versions/1.0/guides/setup.md, por ejemplo) es simplemente editar ese archivo directamente, igual que cualquier otra página.

Qué se construye

Cada versión se construye en site/versions/<name>/, con su propia nav, migas de pan, enlaces anterior/siguiente, y editUri correctamente delimitados a la propia ruta de origen de esa versión. Los nombres de versión se ordenan de más nueva a más antigua, numéricamente en lugar de alfabéticamente - 2.0 se ordena antes que 10.0 - y cada tema incorporado renderiza automáticamente un desplegable selector de versión en la cabecera en cuanto existe más de una versión (el árbol principal "Latest" cuenta como una), sin nada que activar. Cambiar de versión te mantiene en el árbol de la página equivalente cuando es posible.

sitemap.xml y llms.txt incluyen las páginas de cada versión junto a las del sitio principal - una versión es una parte de primera clase, totalmente rastreable/enlazable del sitio, no un archivo oculto.

Combinar con i18n

Consulta i18n: "Docs versionados y traducidos" para la propia convención docs/versions/<name>/i18n/<code>/, que refleja la propia estructura de una versión exactamente de la misma forma que el docs/i18n/<code>/ de nivel superior refleja el propio docs/.

Qué queda fuera de alcance (por ahora)

• La búsqueda está delimitada por árbol, no unificada entre versiones. El proveedor de búsqueda local por defecto escribe un search-index.json separado por árbol durante una construcción real - site/search-index.json para "Latest", site/versions/2.0/search-index.json para la versión 2.0, y así sucesivamente - así que la búsqueda de un visitante solo cubre la versión que está leyendo en ese momento, nunca todas las versiones a la vez. Los verbos independientes de la CLI search-index/search:query van un paso más allá y solo cargan el árbol principal docs/ sin importar cuántas versiones existan, ya que están pensados para una comprobación rápida contra tu documentación actual en curso, no una construcción completa - ejecuta build primero si necesitas el índice real de una versión concreta. El proveedor de búsqueda pagefind es la excepción: rastrea todo el site/ construido en un solo paso, versiones incluidas - consulta Búsqueda.
• Sin marcador de obsoleto/fin de soporte, sin etiqueta personalizada. La entrada del selector de una versión siempre es simplemente el nombre de su carpeta - no hay ninguna configuración para marcar una como no compatible o renombrar su etiqueta mostrada de forma independiente a la carpeta. Archivar una versión antigua significa dejar su carpeta en su sitio (o eliminarla y aceptar los enlaces rotos, igual que al eliminar cualquier otra página).