Skip to content

Commit 3c2a9c6

Browse files
mbarbinmbarbin
authored
Merge pull request #8 from mbarbin/zola
Initiating Zola Documentation Harness
2 parents 9ac9270 + ae76406 commit 3c2a9c6

37 files changed

Lines changed: 1646 additions & 128 deletions

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

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: deploy-doc
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
build:
13+
name: Build documentation
14+
runs-on: ubuntu-latest
15+
16+
env:
17+
MDBOOK_VERSION: "0.5.2"
18+
MDBOOK_DIGEST: "sha256:b7ab218618bb3c1715e3e1759cfa0abc56dcd7ab5d90f60dcd86d708c87b715d"
19+
ZOLA_VERSION: "0.22.1"
20+
ZOLA_DIGEST: "sha256:45de6b2559aba4df42199dc6b0161acb914d37be4ccaa03297cd4a26c8e14042"
21+
22+
defaults:
23+
run:
24+
shell: bash
25+
26+
steps:
27+
- name: Checkout
28+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
29+
30+
- name: Cache mdbook binary
31+
uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2
32+
id: mdbook-cache
33+
with:
34+
path: ~/.local/bin/mdbook
35+
key: mdbook-${{ env.MDBOOK_VERSION }}-${{ runner.os }}-${{ runner.arch }}-${{ env.MDBOOK_DIGEST }}
36+
37+
- name: Install mdbook
38+
env:
39+
BINARY_CACHE_HIT: ${{ steps.mdbook-cache.outputs.cache-hit }}
40+
run: |
41+
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
42+
bash actions/install-mdbook.sh
43+
44+
- name: Cache zola binary
45+
uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2
46+
id: zola-cache
47+
with:
48+
path: ~/.local/bin/zola
49+
key: zola-${{ env.ZOLA_VERSION }}-${{ runner.os }}-${{ runner.arch }}-${{ env.ZOLA_DIGEST }}
50+
51+
- name: Install zola
52+
env:
53+
BINARY_CACHE_HIT: ${{ steps.zola-cache.outputs.cache-hit }}
54+
run: |
55+
bash actions/install-zola.sh
56+
57+
- name: Build documentation
58+
run: make -C doc build
59+
60+
- name: Upload Build Artifact
61+
uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
62+
with:
63+
path: doc/public
64+
65+
deploy:
66+
name: Deploy to GitHub Pages
67+
needs: build
68+
69+
permissions:
70+
pages: write
71+
id-token: write
72+
73+
environment:
74+
name: github-pages
75+
url: ${{ steps.deployment.outputs.page_url }}
76+
77+
runs-on: ubuntu-latest
78+
79+
defaults:
80+
run:
81+
shell: bash
82+
83+
steps:
84+
- name: Deploy to GitHub Pages
85+
id: deployment
86+
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: test-deploy-doc
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
test-deploy:
13+
name: Test deployment
14+
runs-on: ubuntu-latest
15+
16+
env:
17+
MDBOOK_VERSION: "0.5.2"
18+
MDBOOK_DIGEST: "sha256:b7ab218618bb3c1715e3e1759cfa0abc56dcd7ab5d90f60dcd86d708c87b715d"
19+
ZOLA_VERSION: "0.22.1"
20+
ZOLA_DIGEST: "sha256:45de6b2559aba4df42199dc6b0161acb914d37be4ccaa03297cd4a26c8e14042"
21+
22+
defaults:
23+
run:
24+
shell: bash
25+
26+
steps:
27+
- name: Checkout
28+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
29+
30+
- name: Cache mdbook binary
31+
uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2
32+
id: mdbook-cache
33+
with:
34+
path: ~/.local/bin/mdbook
35+
key: mdbook-${{ env.MDBOOK_VERSION }}-${{ runner.os }}-${{ runner.arch }}-${{ env.MDBOOK_DIGEST }}
36+
37+
- name: Install mdbook
38+
env:
39+
BINARY_CACHE_HIT: ${{ steps.mdbook-cache.outputs.cache-hit }}
40+
run: |
41+
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
42+
bash actions/install-mdbook.sh
43+
44+
- name: Cache zola binary
45+
uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2
46+
id: zola-cache
47+
with:
48+
path: ~/.local/bin/zola
49+
key: zola-${{ env.ZOLA_VERSION }}-${{ runner.os }}-${{ runner.arch }}-${{ env.ZOLA_DIGEST }}
50+
51+
- name: Install zola
52+
env:
53+
BINARY_CACHE_HIT: ${{ steps.zola-cache.outputs.cache-hit }}
54+
run: |
55+
bash actions/install-zola.sh
56+
57+
- name: Build documentation
58+
run: make -C doc build

‎Makefile‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,5 +30,9 @@ doc:
3030
clean:
3131
opam exec -- dune clean
3232

33+
.PHONY: shellcheck
34+
shellcheck:
35+
shellcheck actions/*.sh
36+
3337
.PHONY: check-all
34-
check-all: deps all test doc clean lint fmt
38+
check-all: deps all test doc clean lint fmt shellcheck

‎actions/install-mdbook.sh‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
#!/bin/bash
2+
# SPDX-FileCopyrightText: 2026 Mathieu Barbin <mathieu.barbin@gmail.com>
3+
# SPDX-License-Identifier: MIT
4+
# Install mdbook binary from GitHub releases.
5+
#
6+
# Environment variables:
7+
# MDBOOK_VERSION - required, e.g. "0.5.2"
8+
# MDBOOK_DIGEST - optional, e.g. "sha256:abc123..."
9+
# INSTALL_DIR - optional, defaults to "$HOME/.local/bin"
10+
# BINARY_CACHE_HIT - optional, set to "true" to skip download (restored from cache)
11+
12+
set -euo pipefail
13+
14+
: "${ERRORPREFIX:="::error::Fatal error: "}"
15+
16+
abort() {
17+
printf '%s%s\n' "$ERRORPREFIX" "$1"
18+
exit 2
19+
}
20+
21+
install_mdbook() {
22+
BIN_DIR="${INSTALL_DIR:-$HOME/.local/bin}"
23+
mkdir -p "$BIN_DIR"
24+
25+
if [ "${BINARY_CACHE_HIT:-}" = "true" ]; then
26+
echo "mdbook binary restored from cache"
27+
(set -x; "${BIN_DIR}/mdbook" --version)
28+
return
29+
fi
30+
31+
case "$(uname -ms)" in
32+
'Linux x86_64')
33+
target=x86_64-unknown-linux-gnu
34+
;;
35+
'Linux aarch64')
36+
target=aarch64-unknown-linux-gnu
37+
;;
38+
'Darwin x86_64')
39+
target=x86_64-apple-darwin
40+
;;
41+
'Darwin arm64')
42+
target=aarch64-apple-darwin
43+
;;
44+
*)
45+
abort "Unsupported platform: $(uname -ms)"
46+
;;
47+
esac
48+
49+
local url="https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-${target}.tar.gz"
50+
local tmp_dir
51+
tmp_dir="$(mktemp -d)"
52+
53+
(set -x;
54+
curl -fsSL "$url" | tar -xzf - -C "$tmp_dir"
55+
mv "$tmp_dir/mdbook" "$BIN_DIR/"
56+
"${BIN_DIR}/mdbook" --version)
57+
rm -rf "$tmp_dir"
58+
}
59+
60+
verify_digest() {
61+
local binary="$1"
62+
local digest="$2"
63+
local algorithm="${digest%%:*}"
64+
local expected_hash="${digest#*:}"
65+
66+
case "${algorithm}" in
67+
sha256)
68+
local actual_hash
69+
if command -v sha256sum >/dev/null 2>&1; then
70+
actual_hash=$(sha256sum "${binary}" | cut -d ' ' -f 1)
71+
elif command -v shasum >/dev/null 2>&1; then
72+
actual_hash=$(shasum -a 256 "${binary}" | cut -d ' ' -f 1)
73+
else
74+
abort "sha256sum or shasum is required to verify the binary digest"
75+
fi
76+
;;
77+
*)
78+
abort "Digest algorithm '${algorithm}' is not supported. Supported: sha256"
79+
;;
80+
esac
81+
82+
if [ "${actual_hash}" != "${expected_hash}" ]; then
83+
abort "${algorithm}: expected ${expected_hash} but got ${actual_hash} for ${binary}"
84+
fi
85+
echo "Digest verified: ${algorithm}:${actual_hash}"
86+
}
87+
88+
main() {
89+
if [ -z "${MDBOOK_VERSION:-}" ]; then
90+
abort "MDBOOK_VERSION is required"
91+
fi
92+
93+
install_mdbook
94+
95+
if [ -n "${MDBOOK_DIGEST:-}" ]; then
96+
verify_digest "${BIN_DIR}/mdbook" "$MDBOOK_DIGEST"
97+
fi
98+
}
99+
100+
main

‎actions/install-zola.sh‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
#!/bin/bash
2+
# SPDX-FileCopyrightText: 2026 Mathieu Barbin <mathieu.barbin@gmail.com>
3+
# SPDX-License-Identifier: MIT
4+
# Install zola binary from GitHub releases.
5+
#
6+
# Environment variables:
7+
# ZOLA_VERSION - required, e.g. "0.22.1"
8+
# ZOLA_DIGEST - optional, e.g. "sha256:abc123..."
9+
# INSTALL_DIR - optional, defaults to "$HOME/.local/bin"
10+
# BINARY_CACHE_HIT - optional, set to "true" to skip download (restored from cache)
11+
12+
set -euo pipefail
13+
14+
: "${ERRORPREFIX:="::error::Fatal error: "}"
15+
16+
abort() {
17+
printf '%s%s\n' "$ERRORPREFIX" "$1"
18+
exit 2
19+
}
20+
21+
install_zola() {
22+
BIN_DIR="${INSTALL_DIR:-$HOME/.local/bin}"
23+
mkdir -p "$BIN_DIR"
24+
25+
if [ "${BINARY_CACHE_HIT:-}" = "true" ]; then
26+
echo "zola binary restored from cache"
27+
(set -x; "${BIN_DIR}/zola" --version)
28+
return
29+
fi
30+
31+
case "$(uname -ms)" in
32+
'Linux x86_64')
33+
target=x86_64-unknown-linux-gnu
34+
;;
35+
'Linux aarch64')
36+
target=aarch64-unknown-linux-gnu
37+
;;
38+
'Darwin x86_64')
39+
target=x86_64-apple-darwin
40+
;;
41+
'Darwin arm64')
42+
target=aarch64-apple-darwin
43+
;;
44+
*)
45+
abort "Unsupported platform: $(uname -ms)"
46+
;;
47+
esac
48+
49+
local url="https://github.com/getzola/zola/releases/download/v${ZOLA_VERSION}/zola-v${ZOLA_VERSION}-${target}.tar.gz"
50+
local tmp_dir
51+
tmp_dir="$(mktemp -d)"
52+
53+
(set -x;
54+
curl -fsSL "$url" | tar -xzf - -C "$tmp_dir"
55+
mv "$tmp_dir/zola" "$BIN_DIR/"
56+
"${BIN_DIR}/zola" --version)
57+
rm -rf "$tmp_dir"
58+
}
59+
60+
verify_digest() {
61+
local binary="$1"
62+
local digest="$2"
63+
local algorithm="${digest%%:*}"
64+
local expected_hash="${digest#*:}"
65+
66+
case "${algorithm}" in
67+
sha256)
68+
local actual_hash
69+
if command -v sha256sum >/dev/null 2>&1; then
70+
actual_hash=$(sha256sum "${binary}" | cut -d ' ' -f 1)
71+
elif command -v shasum >/dev/null 2>&1; then
72+
actual_hash=$(shasum -a 256 "${binary}" | cut -d ' ' -f 1)
73+
else
74+
abort "sha256sum or shasum is required to verify the binary digest"
75+
fi
76+
;;
77+
*)
78+
abort "Digest algorithm '${algorithm}' is not supported. Supported: sha256"
79+
;;
80+
esac
81+
82+
if [ "${actual_hash}" != "${expected_hash}" ]; then
83+
abort "${algorithm}: expected ${expected_hash} but got ${actual_hash} for ${binary}"
84+
fi
85+
echo "Digest verified: ${algorithm}:${actual_hash}"
86+
}
87+
88+
main() {
89+
if [ -z "${ZOLA_VERSION:-}" ]; then
90+
abort "ZOLA_VERSION is required"
91+
fi
92+
93+
install_zola
94+
95+
if [ -n "${ZOLA_DIGEST:-}" ]; then
96+
verify_digest "${BIN_DIR}/zola" "$ZOLA_DIGEST"
97+
fi
98+
}
99+
100+
main

‎actions/test-install-mdbook.sh‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
#!/bin/sh
2+
# SPDX-FileCopyrightText: 2026 Mathieu Barbin <mathieu.barbin@gmail.com>
3+
# SPDX-License-Identifier: MIT
4+
# Test the mdbook install script locally.
5+
# Usage: ./test-install-mdbook.sh <version> <digest>
6+
set -eu
7+
8+
if [ $# -ne 2 ]; then
9+
echo "Usage: $0 <mdbook-version> <mdbook-digest>" >&2
10+
exit 1
11+
fi
12+
13+
BINARY="mdbook"
14+
FAKE_TMPDIR="$(mktemp -d)"
15+
trap 'rm -rf "${FAKE_TMPDIR}"' EXIT
16+
17+
export MDBOOK_VERSION="$1"
18+
export MDBOOK_DIGEST="$2"
19+
export INSTALL_DIR="${FAKE_TMPDIR}/bin"
20+
21+
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
22+
bash "${SCRIPT_DIR}/install-mdbook.sh"
23+
24+
if [ -x "${INSTALL_DIR}/${BINARY}" ]; then
25+
echo "${BINARY} binary installed successfully at ${INSTALL_DIR}/${BINARY}"
26+
"${INSTALL_DIR}/${BINARY}" --version
27+
else
28+
echo "Error: ${BINARY} binary was not installed in ${INSTALL_DIR}/" >&2
29+
exit 1
30+
fi

0 commit comments

Comments
 (0)