GitHub Pages

Updated Nov 1, 2026

GitHub Pages serves a directory of static files at one of two URL shapes:

User/org site: https://<user>.github.io/, served from a repo named <user>.github.io. No sub-path.
Project site: https://<user>.github.io/<repo>/, served from any other repo. The /<repo>/ prefix matters; page and asset URLs must include it.

Build the site

htmlpress build

Output lands in .htmlpress/build/.

Configure `base` for project sites

If you're publishing under https://<user>.github.io/<repo>/, set base so every root-relative URL in the build gets the prefix. Keep writing links without it (/guides/build/); htmlpress adds it. htmlpress start and preview serve under the same base, so dev matches production:

site: https://acme.github.io
base: /my-docs/

For user/org sites at the root, omit base entirely.

Custom domains skip the /<repo>/ sub-path even on project sites. If you're attaching a domain like docs.example.com, leave base unset and set site to the final domain.

Deploy manually

The simplest one-shot deploy uses the gh-pages package:

htmlpress build
npx gh-pages -d .htmlpress/build --nojekyll --dotfiles

This pushes the build to the gh-pages branch. In your repo settings, set Pages → Source to "Deploy from a branch" and pick gh-pages / / (root).

Keep --nojekyll: a branch deploy runs Jekyll, which drops folders starting with _, and with them the theme in _htmlpress/. --dotfiles keeps .well-known/, where the agent skills live.

Deploy with GitHub Actions

The official Pages actions are the cleanest path: no extra branch, no service tokens.

name: deploy

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@v5
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npx gethtmlpress build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: .htmlpress/build

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

Set Pages → Source to "GitHub Actions" in your repo settings.

Custom domain

Add a CNAME file with your domain to the project, beside your pages:

docs.example.com

Every file in the project that is not a page is copied to the build output as-is, at the same path, so a CNAME next to the root index.html lands at the root of your deployment. Configure the DNS at your registrar (a CNAME record pointing at <user>.github.io) and set the domain in Pages → Custom domain.