Publier la documentation sur GitHub Pages

Cette page décrit le workflow GitHub Actions fourni pour publier automatiquement la documentation VitePress de QForm Builder Community sur GitHub Pages.

Objectif

URL cible :

https://vevedh.github.io/qform-builder-layer/

La version anglaise est disponible sous :

https://vevedh.github.io/qform-builder-layer/en/

Le projet contient une documentation VitePress dans le dossier :

/docs

Le workflow ajouté construit cette documentation puis publie le dossier généré :

docs/.vitepress/dist

Fichier ajouté

.github/workflows/docs.yml

Le workflow est déclenché :

• à chaque push sur main lorsque docs/**, package.json, bun.lock ou le workflow changent ;
• manuellement depuis l’onglet Actions via workflow_dispatch.

Configuration GitHub Pages

Dans le dépôt GitHub :

1. ouvrir Settings ;
2. ouvrir Pages ;
3. dans Build and deployment ;
4. choisir Source: GitHub Actions.

Ensuite, un push sur main lance automatiquement le déploiement.

Gestion automatique du base

Pour un site GitHub Pages de projet, l’URL ressemble souvent à :

https://<username>.github.io/<repository>/

VitePress doit donc recevoir un base correspondant au nom du dépôt :

/<repository>/

Le workflow définit automatiquement :

VITEPRESS_BASE: '/${{ github.event.repository.name }}/'

Et la configuration VitePress lit cette variable :

const siteBase = process.env.VITEPRESS_BASE || '/'

export default defineConfig({
  base: siteBase,
})

Cela permet de garder :

• base: '/' en développement local ;
• base: '/nom-du-repo/' pendant le build GitHub Pages.

Workflow fourni

name: Deploy VitePress docs to GitHub Pages

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'scripts/**'
      - '.github/workflows/docs.yml'
      - 'package.json'
      - 'README.md'
      - 'bun.lock'
  workflow_dispatch:

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'

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

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

jobs:
  build:
    name: Build documentation
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
          bun-version: 1.3.6

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

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

      - name: Build VitePress documentation
        run: bun run docs:build
        env:
          VITEPRESS_BASE: '/${{ github.event.repository.name }}/'

      - name: Upload GitHub Pages artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: docs/.vitepress/dist

  deploy:
    name: Deploy documentation
    needs: build
    runs-on: ubuntu-latest

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

Compatibilité Node.js 24

GitHub migre progressivement l’exécution des actions JavaScript de Node.js 20 vers Node.js 24. Le workflow anticipe cette migration avec :

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'

Il utilise aussi actions/checkout@v6 et actions/configure-pages@v6 afin d’éviter les warnings de dépréciation liés aux anciennes versions basées sur Node.js 20. Le déploiement se relance quand la documentation, les scripts qui valident cette documentation, le workflow, le README, package.json ou bun.lock changent.

Test local

Avant de pousser :

bun install
bun run docs:build
bun run docs:preview

Pour simuler le base GitHub Pages sous Linux/macOS :

VITEPRESS_BASE=/qform-builder-layer/ bun run docs:build

Sous PowerShell :

$env:VITEPRESS_BASE='/qform-builder-layer/'
bun run docs:build
Remove-Item Env:VITEPRESS_BASE

Cas d’un domaine personnalisé

Si la documentation est publiée sur un domaine personnalisé, par exemple :

https://docs.example.com/

il faut utiliser :

VITEPRESS_BASE: '/'

Dans ce cas, adapte la variable dans le workflow ou ajoute une variable GitHub Actions dédiée.

Bonnes pratiques

• Lancer bun run docs:i18n:check avant chaque modification publiée de la documentation.
• Maintenir une page anglaise sous docs/en/ pour chaque page française.

Garde le workflow de documentation séparé du workflow de publication npm. La documentation peut être déployée à chaque mise à jour de contenu, tandis que la publication npm doit rester liée à une version validée.