Saltar a contenido

Publicar la documentación

El sitio público vive en docs.cortex-ia.com.co. El contenido Markdown está en el repositorio cortex-docs, enlazado como submódulo en cortex-hive (docs/). La configuración de MkDocs y el script de build también están en cortex-docs.

Estructura del sitio

Pestaña Contenido
Inicio Portada y mapa de secciones
Infraestructura Stack, despliegue, CI
Arquitectura Visión y taxonomía del sistema
Ingeniería Plataforma core/framework, Cortex Panel runtime
Plugins Handbook, catálogo, SPI — cómo construir plugins
Casos de uso Verticales PMV
Guías Procedimientos operativos
ADRs Decisiones de ingeniería

Repositorio

Qué Dónde
Markdown (ADRs, guías) Repo cortex-docs (submódulo docs/ en cortex-hive)
mkdocs.yml, build, wrangler Raíz de cortex-docs
Validación en CI del monorepo mkdocs build --strict en python-ci.yml (solo build, sin deploy)

Vista local

Desde la raíz de cortex-hive:

git submodule update --init --recursive
uv run mkdocs serve -f docs/mkdocs.yml -a 127.0.0.1:8001

Solo con el repo cortex-docs clonado:

pip install -r requirements.txt
mkdocs serve -a 127.0.0.1:8001

Build de producción

Desde cortex-docs (Cloudflare Pages):

bash scripts/build-pages-staging.sh

Desde cortex-hive:

bash docs/scripts/build-pages-staging.sh

Genera el directorio staging/ listo para publicar. El script usa pip en cortex-docs aislado o uv dentro del monorepo.

Validación estricta local:

uv run mkdocs build --strict -f docs/mkdocs.yml -d ../staging

Despliegue en Cloudflare Pages

Proyecto Pages: cortex-hive. Conecta el repositorio cortex-ia-com-co/cortex-docs (integración Git del dashboard; no hace falta workflow en GitHub).

Campo Valor
Rama de producción main
Framework preset Ninguno
Build command bash scripts/build-pages-staging.sh
Output directory staging
Variable de entorno PYTHON_VERSION = 3.12

Errores habituales

  • Output / o vacío — el build escribe en staging/, no en la raíz.
  • Build command vacío — MkDocs no se ejecuta solo; hace falta el script.
  • Repo incorrecto — si conectas cortex-hive sin submódulos inicializados, docs/ puede llegar vacío al runner de Pages.

Cada push a main en cortex-docs dispara el build en Cloudflare.

Deploy manual (opcional)

bash scripts/build-pages-staging.sh
npx wrangler pages deploy staging --project-name=cortex-hive

Flujo de edición

  1. Edita Markdown en cortex-docs (commit, push a main).
  2. Opcional: actualiza el puntero del submódulo en cortex-hive (git add docs && git commit).
  3. Cloudflare Pages construye y publica automáticamente.

Ver también Repositorios y submódulos.

Referencias