Migrate doc to zola

.github/workflows/deploy-doc.yml

@@ -12,31 +12,23 @@ permissions:
 
 jobs:
   build:
-    name: Build Docusaurus
+    name: Build documentation
     runs-on: ubuntu-latest
+
     env:
       OCAML_VERSION: "5.5"
       DUNE_VERSION: "3.24.2"
       DUNE_DIGEST: "sha256:3a9cac891f0b6086bfbf58d16c6c17ddfd1d493e031b6b43901f585a7f6899c7"
+      ZOLA_VERSION: "0.22.1"
+      ZOLA_DIGEST: "sha256:45de6b2559aba4df42199dc6b0161acb914d37be4ccaa03297cd4a26c8e14042"
+
     defaults:
       run:
         shell: bash
+
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node
-        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
-        with:
-          node-version: 24
-          cache: npm
-          cache-dependency-path: doc/package-lock.json
-
-      - name: Install Docusaurus Dependencies
-        working-directory: ./doc
-        run: npm ci --ignore-scripts
 
       - name: Environment setup
         run: |
@@ -57,19 +49,31 @@ jobs:
       - name: Build Odoc Pages
         run: dune build @doc
 
-      - name: Copy Odoc Pages to Docusaurus Static Directory
+      - name: Copy Odoc Pages to Zola Static Directory
         run: |
           rm -rf doc/static/odoc
           cp -R _build/default/_doc/_html doc/static/odoc
 
-      - name: Build Website
-        working-directory: ./doc
-        run: npm run build
+      - name: Cache zola binary
+        uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2
+        id: zola-cache
+        with:
+          path: ~/.local/bin/zola
+          key: "zola-${{ env.ZOLA_VERSION }}-${{ runner.os }}-${{ runner.arch }}-${{ env.ZOLA_DIGEST }}"
+
+      - name: Install zola
+        env:
+          BINARY_CACHE_HIT: ${{ steps.zola-cache.outputs.cache-hit }}
+        run: |
+          bash actions/install-zola.sh
+
+      - name: Build documentation
+        run: make -C doc build
 
       - name: Upload Build Artifact
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
-          path: doc/build
+          path: doc/public
 
   deploy:
     name: Deploy to GitHub Pages
@@ -89,7 +93,6 @@ jobs:
     defaults:
       run:
         shell: bash
-        working-directory: ./doc
     steps:
       - name: Deploy to GitHub Pages
         id: deployment

.github/workflows/test-deploy-doc.yml

@@ -14,29 +14,21 @@ jobs:
   test-deploy:
     name: Test deployment
     runs-on: ubuntu-latest
+
     env:
       OCAML_VERSION: "5.5"
       DUNE_VERSION: "3.24.2"
       DUNE_DIGEST: "sha256:3a9cac891f0b6086bfbf58d16c6c17ddfd1d493e031b6b43901f585a7f6899c7"
+      ZOLA_VERSION: "0.22.1"
+      ZOLA_DIGEST: "sha256:45de6b2559aba4df42199dc6b0161acb914d37be4ccaa03297cd4a26c8e14042"
+
     defaults:
       run:
         shell: bash
+
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node
-        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
-        with:
-          node-version: 24
-          cache: npm
-          cache-dependency-path: doc/package-lock.json
-
-      - name: Install Docusaurus Dependencies
-        working-directory: ./doc
-        run: npm ci --ignore-scripts
 
       - name: Environment setup
         run: |
@@ -57,11 +49,23 @@ jobs:
       - name: Build Odoc Pages
         run: dune build @doc
 
-      - name: Copy Odoc Pages to Docusaurus Static Directory
+      - name: Copy Odoc Pages to Zola Static Directory
         run: |
           rm -rf doc/static/odoc
           cp -R _build/default/_doc/_html doc/static/odoc
 
-      - name: Build Website
-        working-directory: ./doc
-        run: npm run build
+      - name: Cache zola binary
+        uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2
+        id: zola-cache
+        with:
+          path: ~/.local/bin/zola
+          key: "zola-${{ env.ZOLA_VERSION }}-${{ runner.os }}-${{ runner.arch }}-${{ env.ZOLA_DIGEST }}"
+
+      - name: Install zola
+        env:
+          BINARY_CACHE_HIT: ${{ steps.zola-cache.outputs.cache-hit }}
+        run: |
+          bash actions/install-zola.sh
+
+      - name: Build documentation
+        run: make -C doc build

Makefile

@@ -30,5 +30,9 @@ doc:
 clean:
 	opam exec -- dune clean
 
+.PHONY: shellcheck
+shellcheck:
+	shellcheck actions/*.sh
+
 .PHONY: check-all
-check-all: deps all test doc clean lint fmt
+check-all: deps all test doc clean lint fmt shellcheck

actions/install-zola.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+# SPDX-FileCopyrightText: 2026 Mathieu Barbin <mathieu.barbin@gmail.com>
+# SPDX-License-Identifier: MIT
+# Install zola binary from GitHub releases.
+#
+# Environment variables:
+#   ZOLA_VERSION     - required, e.g. "0.22.1"
+#   ZOLA_DIGEST      - optional, e.g. "sha256:abc123..."
+#   INSTALL_DIR      - optional, defaults to "$HOME/.local/bin"
+#   BINARY_CACHE_HIT - optional, set to "true" to skip download (restored from cache)
+
+set -euo pipefail
+
+: "${ERRORPREFIX:="::error::Fatal error: "}"
+
+abort() {
+  printf '%s%s\n' "$ERRORPREFIX" "$1"
+  exit 2
+}
+
+install_zola() {
+  BIN_DIR="${INSTALL_DIR:-$HOME/.local/bin}"
+  mkdir -p "$BIN_DIR"
+
+  if [ "${BINARY_CACHE_HIT:-}" = "true" ]; then
+    echo "zola binary restored from cache"
+    (set -x; "${BIN_DIR}/zola" --version)
+    return
+  fi
+
+  case "$(uname -ms)" in
+    'Linux x86_64')
+      target=x86_64-unknown-linux-gnu
+      ;;
+    'Linux aarch64')
+      target=aarch64-unknown-linux-gnu
+      ;;
+    'Darwin x86_64')
+      target=x86_64-apple-darwin
+      ;;
+    'Darwin arm64')
+      target=aarch64-apple-darwin
+      ;;
+    *)
+      abort "Unsupported platform: $(uname -ms)"
+      ;;
+  esac
+
+  local url="https://github.com/getzola/zola/releases/download/v${ZOLA_VERSION}/zola-v${ZOLA_VERSION}-${target}.tar.gz"
+  local tmp_dir
+  tmp_dir="$(mktemp -d)"
+
+  (set -x;
+    curl -fsSL "$url" | tar -xzf - -C "$tmp_dir"
+    mv "$tmp_dir/zola" "$BIN_DIR/"
+    "${BIN_DIR}/zola" --version)
+  rm -rf "$tmp_dir"
+}
+
+verify_digest() {
+  local binary="$1"
+  local digest="$2"
+  local algorithm="${digest%%:*}"
+  local expected_hash="${digest#*:}"
+
+  case "${algorithm}" in
+    sha256)
+      local actual_hash
+      if command -v sha256sum >/dev/null 2>&1; then
+        actual_hash=$(sha256sum "${binary}" | cut -d ' ' -f 1)
+      elif command -v shasum >/dev/null 2>&1; then
+        actual_hash=$(shasum -a 256 "${binary}" | cut -d ' ' -f 1)
+      else
+        abort "sha256sum or shasum is required to verify the binary digest"
+      fi
+      ;;
+    *)
+      abort "Digest algorithm '${algorithm}' is not supported. Supported: sha256"
+      ;;
+  esac
+
+  if [ "${actual_hash}" != "${expected_hash}" ]; then
+    abort "${algorithm}: expected ${expected_hash} but got ${actual_hash} for ${binary}"
+  fi
+  echo "Digest verified: ${algorithm}:${actual_hash}"
+}
+
+main() {
+  if [ -z "${ZOLA_VERSION:-}" ]; then
+    abort "ZOLA_VERSION is required"
+  fi
+
+  install_zola
+
+  if [ -n "${ZOLA_DIGEST:-}" ]; then
+    verify_digest "${BIN_DIR}/zola" "$ZOLA_DIGEST"
+  fi
+}
+
+main

actions/test-install-zola.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+# SPDX-FileCopyrightText: 2026 Mathieu Barbin <mathieu.barbin@gmail.com>
+# SPDX-License-Identifier: MIT
+# Test the zola install script locally.
+# Usage: ./test-install-zola.sh <version> <digest>
+set -eu
+
+if [ $# -ne 2 ]; then
+  echo "Usage: $0 <zola-version> <zola-digest>" >&2
+  exit 1
+fi
+
+BINARY="zola"
+FAKE_TMPDIR="$(mktemp -d)"
+trap 'rm -rf "${FAKE_TMPDIR}"' EXIT
+
+export ZOLA_VERSION="$1"
+export ZOLA_DIGEST="$2"
+export INSTALL_DIR="${FAKE_TMPDIR}/bin"
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+bash "${SCRIPT_DIR}/install-zola.sh"
+
+if [ -x "${INSTALL_DIR}/${BINARY}" ]; then
+  echo "${BINARY} binary installed successfully at ${INSTALL_DIR}/${BINARY}"
+  "${INSTALL_DIR}/${BINARY}" --version
+else
+  echo "Error: ${BINARY} binary was not installed in ${INSTALL_DIR}/" >&2
+  exit 1
+fi

doc/.gitignore

@@ -1,20 +1,8 @@
-# Dependencies
-/node_modules
+# Zola build output
+/public
 
-# Production
-/build
-
-# Generated files
-.docusaurus
-.cache-loader
+# Sass cache
+.sass-cache
 
 # Misc
 .DS_Store
-.env.local
-.env.development.local
-.env.test.local
-.env.production.local
-
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*

doc/Makefile

@@ -0,0 +1,12 @@
+.PHONY: build build-site serve clean
+
+build: build-site
+
+build-site:
+	zola build
+
+serve:
+	zola serve
+
+clean:
+	rm -rf public

doc/NOTICE-zolanight

@@ -0,0 +1,25 @@
+The templates and styles in this documentation site are derived from the
+ZolaNight theme by mxaddict (https://github.com/mxaddict/zolanight),
+licensed under the MIT License:
+
+MIT License
+
+Copyright (c) 2022 mxaddict
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

doc/README.md

@@ -1,11 +1,15 @@
 # Building these docs
 
-npm is needed to build the dunolint docs, which are built on
-[docusaurus](https://docusaurus.io/). To install the necessary
-prerequisites and launch a local development server, do:
+[Zola](https://www.getzola.org/) is needed to build the dunolint docs. To install it and launch a local development server, do:
 
 ```shell
 # in the doc folder
-$ npm install
-$ npm run start
+$ zola serve
+```
+
+To produce a static build (output written to `public/`):
+
+```shell
+# in the doc folder
+$ make build
 ```