GitHub Action

Use the GitHub Action when your site should build in a repository workflow.

Minimal Action Step

- name: Build ZeroPress Pages
  uses: zeropress-app/zeropress-build-pages@v1
  with:
    source: ./docs
    destination: ./_site

The action builds static files only. Uploading and deploying are handled by your hosting provider’s own action or CLI.

@v1 follows the latest compatible Build Pages 1.x release. Use @v1.0.0 for the exact initial release or a full commit SHA when the workflow requires an immutable dependency.

Full GitHub Pages Workflow

This workflow is for an origin-root Pages site, such as a user or organization site or a site with a custom domain. GitHub Project Pages served from https://<owner>.github.io/<repository>/ are not supported without a custom domain that maps the site to the origin root.

name: Build and Deploy Docs to GitHub Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

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

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Pages
        uses: actions/configure-pages@v6

      - name: Build ZeroPress Pages
        uses: zeropress-app/zeropress-build-pages@v1
        with:
          source: ./docs
          destination: ./_site

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5

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

Separate Public Directory

Use public-dir when assets live outside Markdown source files.

- name: Build ZeroPress Pages
  uses: zeropress-app/zeropress-build-pages@v1
  with:
    source: ./docs
    public-dir: ./public
    destination: ./_site

Custom Theme

Use theme-path for a local ZeroPress theme.

- name: Build ZeroPress Pages
  uses: zeropress-app/zeropress-build-pages@v1
  with:
    source: ./docs
    public-dir: ./public
    destination: ./_site
    theme-path: ./theme-docs

theme-path takes precedence over the bundled theme input.

Plain npm Command

The bundled Action is the recommended path for a supported origin-root GitHub Pages site. If you prefer to keep the workflow as ordinary shell commands, run the npm package directly and upload the same _site directory.

name: Build and Deploy Docs to GitHub Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

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

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Pages
        uses: actions/configure-pages@v6

      - name: Build ZeroPress Pages
        run: npx --yes @zeropress/build-pages@1 --source ./docs --public-dir ./public --destination ./_site

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5

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

Common Inputs

• source: Markdown source directory. Default: ./docs.
• public-dir: public passthrough directory. Default: same as source.
• destination: generated output directory. Default: ./_site.
• theme: bundled theme name. Default: docs.
• theme-path: custom local theme directory.

See Action Inputs for the full list.

Post-build Steps

Because Build Pages only writes static files, extra steps can run after the build and before upload.

- name: Format generated HTML
  run: npx --yes prettier@3.8.3 --ignore-path /dev/null --write "./_site/**/*.html"

- name: Build Pagefind index
  run: |
    npx --yes pagefind@1.5.2 --site ./_site --output-subdir _zeropress/pagefind
    cp ./_site/_zeropress/search_pagefind.js ./_site/_zeropress/search.js
    rm ./_site/_zeropress/search.json

Post-build tools are optional. Keep them after the Build Pages step and before the upload/deploy step.