Editar y publicar documentación

Destino vigente: Cloudflare Pages: proyecto greencore-docs (URL inicial https://greencore-docs.pages.dev), con salida estática en dist/. La publicación en Sites descrita al final es histórica y no describe el despliegue actual.

Publicación actual en Cloudflare Pages

El sitio es estático: VitePress genera HTML, CSS, JavaScript, buscador local y mapa del sitio. No necesita servidor de aplicación ni base de datos. Cloudflare Pages admite dos formas de publicar: carga directa o integración con Git. El plan Free incluye 500 compilaciones mensuales y hasta 20 000 archivos por sitio (límites oficiales).

Carga directa (flujo vigente)

1. Edita las páginas y añade sus entradas a .vitepress/config.mts.
2. Desde la raíz de greencore-docs, ejecuta node scripts/prepare-source-links.mjs para actualizar las copias descargables de referencia en docs/public/codigo/. Son instantáneas de archivos, no proyectos autónomos.
3. Ejecuta pnpm docs:build: valida enlaces internos y genera páginas, buscador y mapa del sitio en dist/.
4. En el panel de Cloudflare, abre Workers & Pages → greencore-docs → Upload assets y sube el contenido de dist/ (los archivos, no la carpeta) para crear un nuevo despliegue de producción.
5. Espera la confirmación del despliegue antes de anunciar que se actualizó.

La carga directa no publica automáticamente los cambios de Git ni de los archivos Markdown locales: cada actualización requiere un nuevo despliegue. Solo sube la salida estática, nunca los archivos internos ni el repositorio completo.

Los ejemplos C# se verifican por separado desde la raíz de Greencore.

Integración con Git (alternativa)

Ajuste	Valor
Directorio raíz	Raíz de greencore-docs
Comando de compilación	pnpm docs:build
Directorio de salida	dist/

Se incluye pnpm-lock.yaml: consérvalo en Git y utiliza pnpm install --frozen-lockfile para instalar en CI. Configura pnpm 11.19.0 en el entorno de compilación.

Dominio propio

Dominio de documentación: docs.greencore.dev, agregado como dominio personalizado del proyecto Pages. DNS: CNAME docs → greencore-docs.pages.dev, gestionado en Cloudflare. Si se cambia de dominio, repite el alta en Custom domains del proyecto y actualiza el hostname del sitemap en .vitepress/config.mts.

Secuencia de versiones NuGet

La versión actual configurada es 0.0.1-alpha.2. Para las siguientes publicaciones cambia únicamente el sufijo: 0.0.1-alpha.3, 0.0.1-alpha.4 y así sucesivamente hasta 0.0.1-alpha.99. NuGet no permite reemplazar una versión que ya fue publicada, por lo que cada incremento debe publicarse una sola vez.

Publicación histórica en Sites

Sección histórica: la documentación se publicó en Sites, con la configuración de .openai/hosting.json y salida estática en dist/.

1. Editar las páginas y añadir sus entradas a .vitepress/config.mts.
2. Ejecutar node scripts/prepare-source-links.mjs desde esta carpeta.
3. Ejecutar pnpm docs:build para generar la salida estática en dist/.
4. Comprobar la licencia y guardar la revisión exacta en el repositorio del sitio.
5. Empaquetar la salida estática con la configuración, guardar la versión y publicarla mediante Sites.
6. Esperar la confirmación del despliegue antes de anunciar que se actualizó.

Publicar conservaba los permisos actuales; no convertía automáticamente el sitio en público.

Trabajar localmente

Instala Node.js 20 o posterior y pnpm 11.19.0. Desde la raíz de greencore-docs, ejecuta:

pnpm install --frozen-lockfile
pnpm docs:dev

Para generar el sitio:

pnpm docs:build
pnpm docs:preview

La salida publicable es dist/. Publica esa salida, no los archivos internos ni el repositorio completo.

Añadir una página Markdown

1. Crea un archivo dentro de docs/guia o docs/referencia.
2. Escribe un único título principal y organiza el contenido con subtítulos.
3. Identifica el paquete requerido y explica el comportamiento antes del ejemplo.
4. Agrega el enlace en .vitepress/config.mts.
5. Ejecuta la compilación; los enlaces internos rotos deben corregirse antes de publicar.

Usa bloques de código etiquetados como csharp, shell o powershell. Incluye la salida esperada cuando sea determinista. Evita promesas de rendimiento, compatibilidad o publicación que no estén comprobadas.

Qué incluye este sitio

Navegación lateral, índice por página, resaltado de C#, búsqueda local, enlaces entre guías y tema claro/oscuro. El contenido se modifica editando archivos .md; no hay un panel de carga de archivos ni gestión de usuarios.

Antes de publicar, sincroniza docs/public/LICENSE.txt con la licencia de la raíz del repositorio. Una nueva página Markdown también debe revisarse como documentación técnica, no solamente como texto.