Setting up
More Advanced
GitHub & GitHub Pages

the simple GitHub Pages setup works, but requires you to build and push a docs folder every time. Here we replace that with a GitHub Actions workflow that builds and deploys your site automatically on every push

---

Clean up, and update your build script to output to dist

1. If you previously followed the simple GitHub Pages setup and committed a docs folder to your repository, delete it now. The new workflow builds the site itself and doesn’t need a checked-in output folder.
2. Open package.json in your plain text editor and change the build script so it outputs to ../dist instead of ../docs. The whole file should look like this:

{
  "dependencies": {
    "@observablehq/notebook-kit": "latest"
  },
  "scripts": {
    "preview": "notebooks preview --root nbks",
    "build": "notebooks build --root nbks --out ../dist -- *.html"
  }
}

3. Save the file.

Why dist and not docs? dist is a common convention for build output that gets generated, rather than hand-maintained and committed. Once GitHub Actions is building your site for you, there’s no need to commit the built files at all — you’ll add dist/ to your .gitignore (it’s already there if you used the .gitignore from an earlier notebook).

---

Create the GitHub Actions workflow file

1. Copy the YAML below into your plain text editor:

name: Deploy
on:
  workflow_call: {}
  workflow_dispatch: {}
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: \${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v6
      - uses: actions/upload-pages-artifact@v5
        with:
          path: ./dist
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v5

2. Inside your project folder, create a folder called .github, and inside that a folder called workflows (so the path is .github/workflows). Remember the top level folder here begins with a full-stop, so it will be invisible-by-default in your Finder or file system.
3. Save the file you copied as deploy.yml inside that workflows folder, giving the full path .github/workflows/deploy.yml.

What does this file do? It tells GitHub: “whenever someone pushes to the main branch, install dependencies (npm ci), run the build (npm run build), and deploy whatever ends up in the dist folder to GitHub Pages.”

---

Commit, push, and switch GitHub Pages over to GitHub Actions

1. Back in the Terminal, inside your project folder, add, commit, and push your changes:

git add .
git commit -m "add deploy workflow"
git push

2. Go to GitHub and open your project’s repository. Click the Settings tab.
3. Click the Pages item from the sidebar on the left.
4. Under Build and deployment, change the Source to GitHub Actions (if it isn’t already set that way).
5. Click the Actions tab. You should see a workflow run in progress (triggered automatically by your push) — click it to watch its progress.

⚠️ First run may fail. If the very first run failed before you switched the Pages source to GitHub Actions, don’t worry — that’s expected. Click Deploy on the left of the Actions tab, then click the Run workflow button on the right to trigger it manually. This time it should build and deploy successfully.

6. Once the workflow finishes with a green check mark, go back to your repo’s Settings → Pages. You’ll see the live URL for your site there, of the form:

https://<YourUserName>.github.io/<RepoName>

From now on, every time you push a change to main, GitHub Actions will automatically rebuild and redeploy your site — no manual npm run build required.

---