Publicar la documentación¶

Este repositorio convierte Markdown en un sitio estático bilingüe y lo publica en GitLab Pages. El pipeline de documentación es independiente de los pipelines que crean la aplicación y la infraestructura: no necesita credenciales de AWS, Google Cloud ni un estado de Terraform.

El ZIP contiene las fuentes y la automatización. La publicación real comienza cuando se sube el contenido a un proyecto de GitLab con un runner y Pages habilitados; preparar el ZIP no crea ese proyecto ni una URL pública.

Qué se genera¶

Ruta publicada	Contenido
`/`	Portada con elección explícita de idioma
`/es/`	Documentación y buscador en español
`/en/`	Documentación y buscador en inglés
`/es/search/search_index.json`	Índice de búsqueda de español
`/en/search/search_index.json`	Índice de búsqueda de inglés
`/sitemap.xml`	Índice de los dos mapas del sitio
`/build-info.json`	Versiones del generador y commit de documentación

Estas rutas son relativas a la raíz del sitio Pages. Si GitLab sirve el proyecto bajo /grupo/proyecto/, las páginas quedan bajo /grupo/proyecto/es/ y /grupo/proyecto/en/. No se presupone que el sitio ocupe la raíz de un dominio.

El selector de idioma conserva la ruta de la página. Por ejemplo, permite pasar de es/infrastructure/aws/ a en/infrastructure/aws/. Los nombres de archivo son iguales en ambos idiomas; sus títulos y contenido están traducidos.

Probar el sitio en local¶

Requisitos: Python 3.12, acceso a PyPI para la instalación inicial y un navegador. Los comandos se ejecutan desde la carpeta que contiene mkdocs.yml y .gitlab-ci.yml.

python3 -m venv .venv
.venv/bin/python -m pip install --requirement requirements.txt
.venv/bin/python -m pip check
.venv/bin/python scripts/build_docs.py --serve

Abre http://127.0.0.1:8000/. El servidor sirve las dos traducciones y la portada. Para ver una modificación, detén el servidor con Ctrl+C y vuelve a ejecutar el último comando: esta vista previa no incorpora recarga automática.

En PowerShell, utiliza el ejecutable del entorno de Windows:

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --requirement requirements.txt
.\.venv\Scripts\python.exe scripts\build_docs.py --serve

Con GNU Make, la alternativa es:

make install
make serve

Para construir sin iniciar servidor:

.venv/bin/python scripts/build_docs.py

El resultado se escribe en public/. .build/ contiene copias temporales de las fuentes y de los recursos compartidos. Ambos directorios se regeneran y están excluidos de Git. python scripts/build_docs.py --clean elimina únicamente esos dos directorios.

Crear el proyecto de documentación¶

Crea un proyecto vacío en el grupo de GitLab elegido. Un nombre como documentation o cloud-delivery-lab-docs es suficiente. Evita inicializarlo con README si vas a seguir los comandos de arranque siguientes.
Extrae el ZIP y entra en la carpeta del repositorio. Los archivos .gitlab-ci.yml, .gitignore y .editorconfig deben estar en su raíz; no subas el ZIP como un único archivo ni sitúes todo dentro de una subcarpeta adicional.
Comprueba que la opción CI/CD y GitLab Pages están disponibles, y que hay un runner capaz de usar la imagen python:3.12-slim y descargar paquetes de PyPI. Las cuotas o políticas de la cuenta pueden condicionar su ejecución.
Copia desde GitLab la URL SSH o HTTPS del nuevo proyecto de documentación.
Inicializa y sube las fuentes. En el ejemplo, sustituye el valor de DOCS_REMOTE_URL por esa URL.

DOCS_REMOTE_URL='PEGA_AQUI_LA_URL_DEL_NUEVO_PROYECTO'
git init --initial-branch=main
git add .
git commit -m "docs: add bilingual Cloud Delivery Lab documentation"
git remote add origin "$DOCS_REMOTE_URL"
git push --set-upstream origin main

La rama inicial puede llamarse de otra forma. El pipeline utiliza CI_DEFAULT_BRANCH, por lo que publica desde la rama predeterminada configurada en el proyecto, sin depender del nombre main.

Si el proyecto ya tiene contenido, clónalo, crea una rama y revisa una merge request. Integra las configuraciones existentes antes de añadir estos archivos, especialmente .gitlab-ci.yml; no se necesita ningún push --force.

Funcionamiento del pipeline¶

La configuración utiliza la sintaxis actual de GitLab Pages: el trabajo deploy-pages declara pages.publish: public. El destino es GitLab.com o una instancia GitLab 17.10 o posterior; en versiones anteriores hay que revisar las diferencias de sintaxis y gestión de artefactos. Referencia oficial de Pages en CI/CD.

Situación	Validación	Publicación
Push a una rama sin merge request abierta	Sí	Solo si es la rama predeterminada
Merge request	Sí	No
Push a una rama de trabajo con merge request abierta	Se utiliza el pipeline de la merge request para evitar duplicados	No, salvo el pipeline de rama predeterminada que corresponda
Cambio integrado en la rama predeterminada	Sí	Automática, después de validar
Tag	No se crea pipeline con las reglas incluidas	No

validate-docs instala las versiones de requirements.txt y ejecuta scripts/build_docs.py. El script:

Comprueba que todas las páginas tienen equivalente en ambos idiomas y que la navegación está completa.
Copia las fuentes de cada idioma y los recursos comunes a .build/.
Ejecuta MkDocs en modo estricto para español e inglés.
Genera la portada, los mapas del sitio y el manifiesto del build.
Comprueba los enlaces internos, anclas, recursos estáticos, idioma HTML e índices de búsqueda del sitio generado.

Si alguna comprobación falla, el trabajo falla y no se publica. El HTML se entrega como artefacto public/ durante una semana para poder revisarlo.

deploy-pages descarga exactamente el artefacto del trabajo anterior, comprueba su integridad estructural y lo publica. El recurso documentation-pages serializa este trabajo. No vuelve a compilar las páginas y no ejecuta Terraform ni despliega la aplicación demostradora.

La serialización evita dos jobs de publicación simultáneos, pero no garantiza por sí sola que un pipeline antiguo y lento nunca publique después de uno más reciente. En la configuración CI/CD del proyecto, revisa Prevent outdated deployment jobs para proteger el entorno documentation frente a trabajos obsoletos. Es una opción de GitLab; no requiere añadir otro job ni una aprobación manual. Orden de despliegues.

Los enlaces externos a fuentes, proveedores o repositorios no se consultan desde el validador: la comprobación es local y no depende del estado momentáneo de servicios ajenos.

URL del sitio y cambio de nombre del grupo¶

El script determina la URL canónica con esta prioridad:

Prioridad	Valor	Uso
1	`--site-url`	Prueba explícita desde la línea de comandos
2	`DOCS_SITE_URL`	Dominio propio o sustitución deliberada
3	`CI_PAGES_URL`	URL que GitLab proporciona al trabajo
4	`http://127.0.0.1:8000/`	Vista local por defecto

En GitLab CI, si faltan --site-url, DOCS_SITE_URL y CI_PAGES_URL, el build falla con un mensaje explícito. La URL de localhost solo se utiliza como valor por defecto en una ejecución local.

CI_PAGES_URL se lee dentro del script del trabajo, ya que GitLab la define como variable disponible al ejecutar jobs. Incluye el destino de Pages que corresponda; no se construye manualmente concatenando el nombre del grupo y del proyecto. Variables predefinidas.

Para probar una URL con subruta:

.venv/bin/python scripts/build_docs.py \
  --site-url https://example.gitlab.io/group/documentation/

Es una comprobación de enlaces y rutas; no publica nada en ese dominio de ejemplo.

Para un dominio propio configurado en GitLab Pages, añade la variable CI/CD no sensible DOCS_SITE_URL, por ejemplo https://docs.example.org/. Esta variable modifica los enlaces canónicos y de idioma, pero no crea el dominio, el DNS ni el certificado TLS. Configura esas piezas mediante las opciones de Pages. Dominios de Pages.

Los enlaces al repositorio de documentación se obtienen de CI_PROJECT_URL; los enlaces de edición usan CI_DEFAULT_BRANCH. En local se pueden añadir con DOCS_REPO_URL. Cuando no se conoce la URL del nuevo repositorio, se omiten esos enlaces en lugar de inventar un destino.

Después de renombrar el grupo o el proyecto, vuelve a ejecutar el pipeline y revisa Deploy > Pages. Actualiza también las referencias de los repositorios de aplicación e infraestructura y los enlaces a fuentes si su namespace cambió. El ajuste dinámico del sitio no modifica esos otros proyectos.

Comprobar la primera publicación¶

Tras terminar el pipeline:

Abre Deploy > Pages y utiliza la URL que GitLab indique allí; puede ser un dominio único.
Comprueba la portada y ambas opciones de idioma.
Abre una página interior, cambia de idioma y confirma que sigues en el mismo tema.
Prueba la búsqueda en cada idioma y abre un resultado.
Revisa que los diagramas y los bloques de código se muestran correctamente, también en una pantalla estrecha.
Consulta build-info.json para relacionar lo publicado con el commit y las versiones del generador.

La visibilidad del sitio depende de la configuración y de las políticas de Pages del proyecto. Tener el artefacto HTML descargable no equivale a que el sitio se haya publicado.

Resolver incidencias del sitio¶

Síntoma	Comprobación y acción
No aparece ningún pipeline	Confirma que `.gitlab-ci.yml` está en la raíz, que CI/CD está habilitado y que el cambio se ha enviado a una rama admitida.
Job pendiente	Revisa disponibilidad, etiquetas y permisos del runner; esta configuración no impone etiquetas.
Error de instalación	Usa Python 3.12 y comprueba el acceso a PyPI. Mantén unido el conjunto de versiones del lock.
Falta una traducción	Añade el mismo archivo bajo `docs/es/` y `docs/en/`, y registra ambos en su navegación.
MkDocs falla por un enlace	Corrige la ruta relativa `.md` o el ancla indicada. No reduzcas el nivel de validación para ocultarlo.
La rama de trabajo no publica	Es el comportamiento previsto. La publicación se ejecuta en la rama predeterminada después de una validación correcta.
Pages devuelve 404	Comprueba el estado del trabajo Pages, la URL en `Deploy > Pages` y la existencia de `public/index.html` en el artefacto.
El cambio de idioma pierde la subruta	Revisa `DOCS_SITE_URL` y `CI_PAGES_URL`. El dominio debe incluir toda la raíz real del sitio, con su subruta.
Un dominio propio muestra enlaces a otro dominio	Ajusta `DOCS_SITE_URL` a la URL canónica y recompila.
El build funciona pero una fuente externa no abre	Comprueba el enlace y sus permisos por separado; el validador local no autentica ni verifica fuentes externas.

Archivos que mantienen este servicio¶

Archivo	Responsabilidad
`mkdocs.yml`	Tema, extensiones y validación comunes
`mkdocs.es.yml`, `mkdocs.en.yml`	Navegación y búsqueda de cada idioma
`scripts/build_docs.py`	Dos builds, portada, URLs y recursos compartidos
`scripts/check_docs.py`	Paridad de traducción y navegación
`scripts/check_site.py`	Enlaces, anclas y recursos del HTML generado
`.gitlab-ci.yml`	Validación y publicación de Pages
`requirements.in`, `requirements.txt`	Dependencias directas y conjunto probado de versiones
`theme/`	Apariencia y adaptaciones de plantillas
`third_party/`	Licencias y versión de Mermaid incorporado

Para modificar contenidos, consulta Mantener y traducir. Para distinguir evidencias del proyecto de decisiones propias de esta documentación, consulta Fuentes y revisión.