Déploiement

Ardo produit un site entièrement statique. La documentation reste dans le dépôt, se construit dans votre CI et se déploie partout où des fichiers peuvent être servis. pnpm build prérend chaque page en HTML statique : aucun serveur n’est requis à l’exécution.

Sortie du build

La sortie par défaut, build/client/, convient à tout hébergeur statique. outDir modifie le répertoire parent des builds client/ et server/; adaptez l’hébergement pour servir son sous-dossier client/. La structure reflète les URL publiées :

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

• Chaque page est un répertoire contenant index.html. Les liens internes se terminent par une barre oblique, comme /guide/getting-started/, pour éviter les redirections de l’hébergeur.
• 404.html traite les pages introuvables. GitHub Pages, Netlify, Cloudflare Pages et la plupart des hébergeurs le reconnaissent automatiquement.
• Le build vérifie chaque lien et ancre interne du HTML. linkCheck permet de faire échouer le build sur les liens cassés.
• Aucun routeur côté client : chaque lien charge le document prérendu suivant, puis l’hydrate. L’hébergeur sert uniquement des fichiers.

pnpm preview sert build/client/ comme un hébergeur statique : /guide ouvre guide/index.html et les chemins inconnus reçoivent la 404.html la plus proche.

GitHub Pages

Étape 1 : configurer le chemin de base

Un site de projet GitHub Pages se trouve sous le nom du dépôt, par exemple https://username.github.io/my-docs/. Définissez ce chemin comme base dans ardo.config.ts:

import { defineArdoConfig } from "ardo/config"

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

Ce chemin se configure une seule fois. Ardo l’applique aux ressources et liens en développement comme au build, et écrit build/client/ pour que son contenu constitue la racine du site GitHub Pages. Aucun script après build n’est nécessaire.

Omettez base pour un déploiement à https://username.github.io/ ou sous un domaine personnalisé. Le site est servi à la racine du domaine :

import { defineArdoConfig } from "ardo/config"

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

Étape 2 : ajouter un workflow GitHub Actions

Créez .github/workflows/deploy.yml dans le dépôt :

L’exemple épingle pnpm explicitement. Choisissez la version qui a créé votre fichier de verrouillage. Si package.json utilise déjà packageManager, omettez l’entrée version de l’action afin qu’elle respecte ce réglage.

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

Étape 3 : activer GitHub Pages

Dans les paramètres du dépôt, ouvrez Pages et choisissez GitHub Actions comme source.

Un push vers main déclenche alors automatiquement le build et le déploiement.

Pour un domaine personnalisé, renseignez-le dans ces mêmes paramètres avant de modifier le DNS. Avec un workflow Actions personnalisé, GitHub conserve le domaine dans les paramètres du dépôt ; aucun fichier CNAME n’est requis dans la sortie du build.

Documentation GitHub Pages par version majeure

Pour des URL stables par version majeure, construisez la version actuelle dans son dossier et conservez les anciennes versions dans leurs dossiers statiques :

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

Configurez les versions Ardo dans 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 définit le chemin de base du build actuel sur son dossier de version. Les pages et ressources sont écrites sous build/client/v3/; les fichiers communs comme versions.json, robots.txt et la redirection racine restent à la racine de build/client/. Le sélecteur en bas de la barre latérale charge l’autre version comme une nouvelle page.

Le sitemap ne liste que la version majeure actuelle. Les anciens dossiers restent accessibles sans être annoncés comme contenu actuel dupliqué. Sur GitHub Pages, la redirection racine est une index.html statique. Configurez hors d’Ardo les redirections HTTP si votre CDN ou hébergeur les prend en charge.

Si versions.json référence d’anciennes versions, ne téléversez pas uniquement le nouveau build/client. GitHub Pages remplace tout l’artefact à chaque déploiement. Avant actions/upload-pages-artifact, combinez donc le build actuel et les anciens dossiers conservés dans un répertoire de préparation.

Netlify

Netlify n’exige aucun fichier de workflow. Connectez le dépôt Git dans son tableau de bord et configurez :

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

Netlify détecte automatiquement la version de Node.js depuis le champ engines de package.json ou un fichier .nvmrc.

Un site à la racine n’a pas besoin de chemin de base. Définissez base dans ardo.config.ts uniquement pour un sous-chemin.

Vercel

Connectez le dépôt Git dans le tableau de bord Vercel et configurez :

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

Vercel gère automatiquement le routage et le CDN.

Autres hébergeurs

Les fichiers statiques ordinaires de build/client/ conviennent à tout hébergeur : Cloudflare Pages, AWS S3 avec CloudFront, Firebase Hosting, etc. Utilisez pnpm build comme commande et build/client comme répertoire de sortie.