Despliegue

Ardo genera un sitio completamente estático. La documentación puede vivir en el repositorio, compilarse en CI y publicarse en cualquier proveedor que sirva archivos. pnpm build prerenderiza todas las páginas como HTML estático: no hace falta servidor en ejecución.

Salida de compilación

La salida predeterminada es build/client/, válida para cualquier alojamiento estático. outDir cambia el directorio padre de client/ y server/; ajusta el alojamiento para servir su subcarpeta client/. La estructura refleja las URL publicadas:

build/client/
├── index.html                  # Home page
├── 404.html                    # Not-found page
├── guide/
│   └── getting-started/
│       └── index.html          # /guide/getting-started/
├── assets/                     # Hashed JavaScript and CSS
├── sitemap.xml
├── robots.txt
└── llms.txt

• Cada página es un directorio con index.html. Los enlaces internos terminan con una barra, como /guide/getting-started/, para que el alojamiento estático los sirva sin redirecciones.
• 404.html es la página para rutas desconocidas. GitHub Pages, Netlify, Cloudflare Pages y la mayoría de proveedores la reconocen automáticamente.
• La compilación comprueba todos los enlaces y anclas internos del HTML. linkCheck permite fallar si hay enlaces rotos.
• No hay router del cliente. Cada enlace carga el siguiente documento prerenderizado y después lo hidrata. El proveedor solo sirve archivos.

pnpm preview sirve build/client/ como un alojamiento estático: /guide abre guide/index.html y las rutas desconocidas reciben la 404.html más cercana.

GitHub Pages

Paso 1: configurar la ruta base

Un sitio de proyecto GitHub Pages vive bajo el nombre del repositorio, por ejemplo https://username.github.io/my-docs/. Define ese camino como base en ardo.config.ts:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  title: "My Docs",
  base: "/my-docs/",
})

La ruta base se configura una sola vez. Ardo la aplica a los recursos y enlaces en desarrollo y producción, y escribe build/client/ de modo que su contenido sea la raíz del sitio en GitHub Pages. No hace falta un script posterior.

Omite base si publicas en https://username.github.io/ o bajo un dominio propio. El sitio se sirve desde la raíz del dominio:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  title: "My Docs",
  siteUrl: "https://docs.example.com",
})

Paso 2: añadir un workflow de GitHub Actions

Crea .github/workflows/deploy.yml en el repositorio:

El ejemplo fija la versión de pnpm. Usa la que creó tu archivo de bloqueo. Si package.json ya incluye packageManager, omite el parámetro version de la acción para que use esa versión.

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Setup pnpm
        uses: pnpm/action-setup@v6
        with:
          version: "12.14.0"

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: "22"
          cache: "pnpm"

      - name: Setup Pages
        uses: actions/configure-pages@v6

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build
        run: pnpm build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: build/client

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

Paso 3: activar GitHub Pages

En la configuración del repositorio, abre Pages y elige GitHub Actions como fuente.

Al hacer push a main, el workflow compila y despliega el sitio automáticamente.

Si usas un dominio propio, añádelo en esa misma configuración antes de cambiar DNS. En un workflow de Actions personalizado, GitHub almacena el dominio en la configuración del repositorio; no hace falta un archivo CNAME en la salida.

Documentación por versiones principales en GitHub Pages

Para URL estables, compila la documentación actual en una carpeta de versión y conserva las anteriores como carpetas estáticas:

/          -> static HTML redirect to /v3/
/v3/       -> current major docs
/v2/       -> previous major docs
/versions.json

Configura las versiones de Ardo en ardo.config.ts:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  title: "My Docs",
  siteUrl: "https://docs.example.com",
  versioning: {
    current: "v3",
    versions: [
      { id: "v3", label: "3.x", path: "/v3/" },
      { id: "v2", label: "2.x", path: "/v2/" },
    ],
  },
})

versioning establece la ruta base del build actual en su carpeta de versión. Ardo escribe las páginas y recursos bajo build/client/v3/; los archivos comunes como versions.json, robots.txt y la redirección raíz quedan en la raíz de build/client/. El selector al final de la barra lateral carga la otra versión como una página nueva.

El sitemap solo enumera la versión principal actual. Las anteriores siguen accesibles sin anunciarse como contenido actual duplicado. En GitHub Pages, la redirección raíz es un index.html estático. Configura fuera de Ardo las redirecciones HTTP si tu CDN o proveedor las admite.

Si versions.json incluye versiones anteriores, no subas únicamente el nuevo build/client. GitHub Pages sustituye todo el artefacto en cada despliegue. Antes de actions/upload-pages-artifact, combina el build actual y las carpetas antiguas conservadas en un directorio de preparación.

Netlify

Netlify no necesita un workflow. Conecta tu repositorio Git en el panel y configura:

• Build command:pnpm build
• Publish directory:build/client

Netlify detecta automáticamente la versión de Node.js desde el campo engines de package.json o un archivo .nvmrc.

Un sitio en la raíz no necesita ruta base. Define base en ardo.config.ts solo para subrutas.

Vercel

Conecta tu repositorio Git en el panel de Vercel y configura:

• Build command:pnpm build
• Output directory:build/client
• Framework preset: Other

Vercel gestiona automáticamente las rutas y el CDN.

Otros proveedores

Los archivos estáticos de build/client/ sirven para cualquier proveedor, incluidos Cloudflare Pages, AWS S3 con CloudFront y Firebase Hosting. Usa pnpm build como comando de compilación y build/client como directorio de salida.