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/**'
      - '.github/workflows/docs.yml'
      - 'package.json'
      - '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.

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.