#Deploy to GitHub Pages

Deploy your ciderpress documentation site to GitHub Pages using a GitHub Actions workflow.

#Prerequisites

• A GitHub repository with your ciderpress project
• ciderpress building locally (npx ciderpress build succeeds)
• A committed lockfile (pnpm-lock.yaml or package-lock.json) — --frozen-lockfile / npm ci fail without one
• Repository admin access (to enable GitHub Pages)

#Steps

#1. Add output directories to gitignore

Add the ciderpress output root to .gitignore — its contents are regenerated by sync and build:

.ciderpress/

#2. Create the GitHub Actions workflow

Create .github/workflows/deploy-docs.yml:

name: Deploy Docs
on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '24'
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec ciderpress build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: .ciderpress/dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

If you use npm instead of pnpm, replace the pnpm-specific steps:

- uses: actions/setup-node@v4
  with:
    node-version: '24'
    cache: npm
- run: npm ci
- run: npx ciderpress build

#3. Enable GitHub Pages

1. Go to your repository Settings > Pages
2. Under Source, select GitHub Actions

#4. Push to main

Push your changes to the main branch to trigger the first deployment.

#Verification

After the workflow completes, open the URL shown in the GitHub Actions deployment step output. You should see your documentation site with all pages, navigation, and search working.

Check the workflow status at Actions > Deploy Docs in your repository.

#Troubleshooting

#Workflow fails at deploy step

Symptom: The build job succeeds but the deploy job fails with a permissions error.

Fix: Ensure GitHub Pages source is set to GitHub Actions (not "Deploy from a branch") in Settings > Pages.

#404 on subpaths

Symptom: The home page loads but navigating to other pages returns 404.

Cause: GitHub Pages does not support client-side routing by default.

Fix: ciderpress builds to static HTML with one file per route, so this should not happen. If it does, verify that .ciderpress/dist contains individual .html files for each page.

#Custom domain

To use a custom domain, add a step to the build job (after the ciderpress build step, before the upload-pages-artifact step) that writes a CNAME file:

- run: echo "docs.example.com" > .ciderpress/dist/CNAME

Then configure your DNS to point to GitHub Pages. See the GitHub Pages custom domain docs for full DNS setup instructions.

#References

• CLI reference — build
• CLI reference — sync
• Content — how pages and sections are defined