Docs site: Zensical → GitHub Pages (parity with IcebergTTX/EBS)

.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: Documentation
+
+# Build the Zensical site under website/ and deploy to GitHub Pages.
+# Requires: Settings → Pages → Source = "GitHub Actions".
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "website/**"
+      # changelog.md snippet-includes the repo-root CHANGELOG.md, so a
+      # changelog-only commit must also rebuild the site.
+      - "CHANGELOG.md"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; don't cancel an in-progress one.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: website
+    steps:
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.x"
+      # Pin the version (parity with zizmor==/actionlint checksum pins in ci.yml):
+      # this job holds pages:write + id-token:write, so a yanked/compromised
+      # zensical release must not silently change the build.
+      - run: pip install zensical==0.0.50
+      - run: zensical build --clean
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
+        with:
+          path: website/site
+      - uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5
+        id: deployment

.gitignore

@@ -22,3 +22,7 @@ htmlcov/
 settings.json
 # Cached standalone Tailwind binary (downloaded by scripts/vendor_assets.py)
 frontend/.bin/
+
+# Zensical docs site build output + incremental cache (website/, #243)
+website/site/
+website/.cache/

website/README.md

@@ -0,0 +1,24 @@
+# Iceberg documentation site
+
+The public docs site — built with [Zensical](https://zensical.org/) (the
+Material-based static site generator) from `docs/` + `zensical.toml`, styled to
+the shared Iceberg design system (`docs/stylesheets/iceberg.css`, self-hosted
+fonts).
+
+Deployed to GitHub Pages by `.github/workflows/docs.yml` on every push to
+`main` touching `website/**` (Settings → Pages → Source = "GitHub Actions").
+The build pins `zensical==0.0.50` — bump deliberately, in step with the
+sibling IcebergTTX/EBS sites.
+
+Preview locally:
+
+```bash
+pip install zensical==0.0.50
+cd website
+zensical serve          # http://localhost:8000, live reload
+zensical build --clean  # writes site/ (gitignored)
+```
+
+Screenshots under `docs/assets/` are copies of the README set in
+`../docs/images/` — regenerate those first (`docs/screenshots/README.md`),
+then re-copy the subset used here.