Déployer sur GitHub Pages

Cette recette est le flux que juicer.build utilise lui-même (et le même flux que la documentation de squiggly). Elle construit votre site avec juicer dans un exécuteur GitHub Actions et pousse le résultat vers GitHub Pages — pas de service de construction tiers, pas d’étape de déploiement distincte, pas de gestion manuelle d’une branche gh-pages.

La forme du déploiement

push sur `stable`  ──▶  tâche build  ──▶  tâche deploy  ──▶  https://<owner>.github.io/<repo>/
                        (sbt build)       (actions/deploy-pages)

Deux tâches GitHub Actions, un seul fichier de workflow. La tâche build exécute juicer build et téléverse le site rendu comme artefact Pages ; la tâche deploy, conditionnée à la branche stable, prend cet artefact et le publie dans l’environnement github-pages. Les poussées sur d’autres branches exécutent quand même build (un contrôle de cohérence), mais l’artefact est téléversé comme fichier téléchargeable plutôt que publié.

Prérequis

Le fichier de workflow

Déposez ceci dans .github/workflows/docs.yml :

# Build & deploy <https://<owner>.github.io/<repo>/>.
#
#   Push to `stable`       → builds and deploys to GitHub Pages.
#   PR targeting `stable`  → builds (sanity check), no deploy.
#   workflow_dispatch      → manual trigger from the Actions tab.

name: Docs

on:
  push:
    branches: ["stable"]
  pull_request:
    branches: ["stable"]
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: "docs-${{ github.ref }}"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "17"

      # actions/setup-java does NOT ship sbt. Install it via the
      # official sbt-maintained action.
      - name: Set up sbt
        uses: sbt/setup-sbt@v1

      - name: Cache sbt
        uses: actions/cache@v4
        with:
          path: |
            ~/.sbt
            ~/.cache/coursier
          key: ${{ runner.os }}-sbt-${{ hashFiles('**/build.sbt', '**/project/**') }}
          restore-keys: ${{ runner.os }}-sbt-

      - name: Build docs site
        run: sbt 'juicerJVM/run build -s docs -d _site -b https://<owner>.github.io/<repo>/'

      - name: Upload site artifact
        uses: actions/upload-artifact@v4
        with:
          name: docs-site
          path: _site

      - name: Upload Pages artifact
        if: github.ref == 'refs/heads/stable'
        uses: actions/upload-pages-artifact@v3
        with:
          path: _site

  deploy:
    if: github.ref == 'refs/heads/stable'
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Remplacez <owner> et <repo> dans le drapeau -b de l’étape Build docs site (p. ex. -b https://edadma.github.io/juicer/). Se tromper ici est le bogue de déploiement le plus courant — chaque lien que juicer émet est calculé par rapport à baseURL, donc une valeur périmée envoie les visiteurs vers le mauvais hôte.

Ce que fait chaque étape

Pages de projet vs pages d’utilisateur/organisation

Il y a deux formes d’URL GitHub Pages, et le drapeau -b doit correspondre à celle que vous utilisez :

Les pages de projet ont un préfixe de chemin (/<repo>/) ; les pages d’utilisateur/organisation non. Trompez-vous et chaque lien interne renverra une 404. Lancez juicer config -s docs -b <votre-url> localement pour afficher le baseURL résolu et revérifier avant de pousser.

Domaine personnalisé (façon juicer.build)

Pour déployer sur un domaine que vous possédez — docs.example.com, example.com, ou autre — étendez le workflow avec deux petites choses :

- name: Write CNAME
  if: github.ref == 'refs/heads/stable'
  run: echo 'docs.example.com' > _site/CNAME

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Aperçus de pull-request

Le workflow tel qu’écrit téléverse docs-site comme artefact ordinaire à chaque PR — vous pouvez le télécharger depuis l’onglet Actions et le servir localement :

unzip docs-site.zip -d /tmp/preview
cd /tmp/preview
python3 -m http.server 8000

Pour de véritables URL d’aperçu par PR (chaque branche a sa propre <branch>.<project>.pages.dev), remplacez GitHub Pages par Cloudflare Pages : connectez le dépôt à un projet Cloudflare Pages, réglez la commande de construction sur sbt 'juicerJVM/run build -s docs -d _site -b $CF_PAGES_URL', et le répertoire de sortie sur _site. Cloudflare attribue des URL d’aperçu automatiquement ; la production pointe vers votre domaine personnalisé.

Dépannage

Le workflow échoue à Upload Pages artifact avec « Pages is not enabled »

Vous n’avez pas encore activé Pages. Settings → Pages → Source : « GitHub Actions ». Le premier déploiement après activation peut prendre une minute ou deux pour que l’environnement s’enregistre.

Le site se construit mais chaque lien renvoie une 404

baseURL est erroné. Lancez sbt 'juicerJVM/run config -s docs -b <votre-url>' localement et inspectez la valeur baseURL — elle doit correspondre à ce que les visiteurs tapent dans le navigateur. Erreurs courantes : barre oblique finale manquante, mauvais préfixe /<repo>/ pour les déploiements en pages d’utilisateur.

Le CSS et le JS se chargent, mais les images renvoient une 404

Les chemins d’image dans votre markdown sont absolus (/img/x.png) mais votre site est sous un préfixe de chemin de projet (/<repo>/). Deux correctifs :

• Utilisez l’assistant de gabarit relURL sur chaque lien/image émis par les gabarits — <img src="{{ relURL '/img/x.png' }}">.
• Dans le corps markdown, écrivez les chemins sans la barre oblique initiale (img/x.png) et laissez le moteur de rendu markdown les calculer par rapport à la page.

La construction réussit localement mais échoue en CI

Deux coupables habituels :

• Version de sbt : assurez-vous que votre project/build.properties local fixe une version de sbt que le sbt/setup-sbt@v1 de l’exécuteur connaît. La dernière 1.x.x convient toujours.
• Version du JDK : la CI utilise java-version: "17". Si vous construisez localement avec le JDK 21, vérifiez l’utilisation d’API propres à Java 21 et fixez votre JDK local à 17 pour la parité.

Les déploiements restent bloqués à « Deploy to GitHub Pages »

Les déploiements concurrents font la queue. Vérifiez Actions → exécutions récentes — une exécution antérieure est probablement encore en cours. Le bloc concurrency: empêche l’empilement des déploiements depuis la même référence, mais les déploiements de références croisées (p. ex. stable + une poussée de tag en même temps) attendent leur tour.

Voir aussi

• DEPLOY.md dans le dépôt juicer — le fichier décrivant le déploiement de juicer.build lui-même. La forme est identique à cette page ; les différences sont notées dans DEPLOY.md.
• Documentation GitHub Pages pour les détails côté plateforme (HTTPS, CNAME, domaines personnalisés, limites de requêtes).