From aa520b47fc66bdf69a1932bb565f66621c2ea863 Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Tue, 22 Sep 2026 08:40:34 +1200 Subject: [PATCH] Move docs to Github pages --- .github/workflows/docs.yaml | 67 +++++++++++++++++++++++++++++++++++++ docs/README.md | 8 +++-- docs/public/CNAME | 1 + 3 files changed, 74 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/docs.yaml create mode 100644 docs/public/CNAME diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..92bedc7 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,67 @@ +name: Build and deploy the docs site + +on: + workflow_dispatch: + push: + branches: + - main + paths: + - 'docs/**' + - '.github/workflows/docs.yaml' + +permissions: + contents: read + pages: write + id-token: write + +# One deploy at a time, and let a running one finish rather than cancelling it part-way. +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + # Full history: VitePress reads git timestamps for the "last updated" line. + fetch-depth: 0 + + - name: Set up Node + uses: actions/setup-node@v4 + with: + node-version: lts/* + cache: npm + cache-dependency-path: docs/package-lock.json + + - name: Install dependencies + run: npm ci + working-directory: docs + + # Dead internal links fail the build, which fails the workflow and leaves the live site untouched. + - name: Build site + run: npm run build + working-directory: docs + + - name: Configure Pages + uses: actions/configure-pages@v5 + + - name: Upload build output + uses: actions/upload-pages-artifact@v3 + with: + path: docs/.vitepress/dist + + deploy: + 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@v4 diff --git a/docs/README.md b/docs/README.md index 4e5716d..0db2e54 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,9 +22,13 @@ npm run build # fails on dead internal links; run it before pushing ``` The sidebar is hand-maintained in `.vitepress/config.ts`, so a new page is invisible until it is added there. -Publishing the built site is a manual step done by the maintainer; a push to `main` does not deploy anything -by itself. Static files (images, favicon) live in `public/` and are referenced by absolute path, e.g. `/share-link.webp`. +`public/CNAME` holds the custom domain; it is copied to the root of the build and must stay there. + +Publishing is automatic. Any push to `main` that touches `docs/` runs the `docs.yaml` workflow, which builds the +site and deploys it to GitHub Pages at [docs.ipp.nz](https://docs.ipp.nz). A dead link fails the build, so the +workflow fails and the live site stays on the previous version. Run `npm run build` yourself before pushing rather +than finding out from a red tick. ## Structure diff --git a/docs/public/CNAME b/docs/public/CNAME new file mode 100644 index 0000000..74fc3c3 --- /dev/null +++ b/docs/public/CNAME @@ -0,0 +1 @@ +docs.ipp.nz