Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Antora docs site has no version selector — pin per release instead of a single unversioned component

Abierto
  • ¿Algo no está bien?
#976 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
git, yaml
Área
documentation

Línea de trabajo

Read docs/antora.yml and antora-playbook.yml to understand the current component version and content sources; first resolve the versioning and tag-retention policy described in the issue. Done means the site exposes selectable release versions alongside develop, with the chosen default and release-update process defined. #975 must be fixed separately for the site to deploy.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Summary

`docs/antora.yml` declares `version: ~` — Antora's syntax for an explicitly
unversioned component. The published site (once #975 is also fixed so it deploys
at all) only ever shows one snapshot of the docs, with no way to view the docs as they
were for an older release (e.g. 0.39.x) versus current `develop`. The workflow's own
comment acknowledges this is deliberate scope-narrowing: "Single-version for now; a
dedicated multi-repo aggregation site can come later."

This matters concretely for this session's work: SKEEP-002/003 landed on `develop`
and are reachable from tag `0.40.1`, but a reader on the live site has no way to know
"is this SKEEP status current as of the latest release, or has it moved since." Same
class of problem applies to any API/behavior doc that changes between releases.

Proposed direction (not prescriptive — Antora supports several shapes here)

Antora has first-class multi-version support: each content source
(playbook `content.sources`) can point at multiple git refs (branches/tags), and each
ref's `antora.yml` `version:` becomes a selectable entry in the generated version
dropdown, with the highest `display_version`/`prerelease: false` version becoming the
default landing page.

Sketch:

  1. Set `version:` in `docs/antora.yml` per release (e.g. `version: '0.40'`,
    `display_version: '0.40.1'`) instead of `~`, updated as part of the existing
    `release: prepare X.Y.Z` commit pattern (SKaiNET-transformers already has this
    commit type; mainline doesn't yet but could adopt it, or just bump the antora.yml
    version field wherever the version bump currently happens).
  2. `antora-playbook.yml`'s `content.sources` adds tag refs (e.hg. `tags: 0.39., 0.40.`
    or an explicit allowlist) alongside `branches: develop`, so Antora builds one page
    tree per historical version from the tagged source at that point in time.
  3. Decide a retention policy (all tags forever vs. last N minor versions) — full
    history multiplies build time and site size per version.

Related

  • #975 — the site currently doesn't deploy at all (gated on a GitHub Release this
    repo never creates); fix that first, independent of this.
  • The same `version: ~` pattern exists in SKaiNET-transformers' `docs/antora.yml`
    (same Docker image, same Antora setup) — filing a companion issue there rather than
    scoping this one cross-repo, since the playbooks/CI are maintained separately.
Lenguaje dominante
Kotlin
Estrellas
52
Forks
15
Merge medio
1 d 15 h
PR fusionados (30 d)
36

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de SKaiNET-developers/SKaiNET

Todos los issues de SKaiNET-developers/SKaiNET

Issues similares

Más issues de Kotlin

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.