GitHub Pages (Actions)

Build with GitHub Actions, run Headlark on the output, then upload it to Pages. In the repository, set Settings → Pages → Source to GitHub Actions, and add your site's secret key from the dashboard as a repository secret named HEADLARK_KEY (Settings → Secrets and variables → Actions).

# .github/workflows/pages.yml
name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: pages
  cancel-in-progress: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run build
      - run: npx headlark dist --site-url https://example.com
        env:
          HEADLARK_KEY: ${{ secrets.HEADLARK_KEY }}
      - uses: actions/upload-pages-artifact@v3
        with:
          path: 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

Install the CLI as a dev dependency (npm i -D headlark) so npx uses the version in your lockfile. Change dist to your framework's output folder (out for a Next.js export) in both places.

Site URL

Use your custom domain or https://<user>.github.io. A project site is served under /<repo>/: include that path, --site-url https://<user>.github.io/<repo>/, and build with the same base (Vite: base: "/<repo>/", Astro: base: "/<repo>", Next.js: basePath: "/<repo>"). Headlark CLI 0.1.2 and older dropped the path; update with npm i -D headlark@latest.

Good to know