Publishing with GitHub Pages

How GitHub Pages URLs Work

Once Pages is enabled, your site is served at:

https://<username>.github.io/<repo-name>/

Files are accessible by appending their path to that base URL:

• A file named index.html at the root of your published folder is served at the base URL — no filename needed. It's the default landing page.
• Any other file, e.g. map.html, is accessible at:
  https://<username>.github.io/<repo-name>/map.html
• A file in a subfolder, e.g. results/summary.html, is at:
  https://<username>.github.io/<repo-name>/results/summary.html

Tip: rename your main output file index.html so you can share a clean, memorable link.

Publishing Only Part of Your Repo

You can designate any folder (e.g. docs/ or output/) as the root of your published site. Only the files in that folder become public — your notebooks, raw data, and source code stay private.

A common pattern:

• Keep all your work in the repo root
• Export final outputs (HTML reports, maps, charts) into a docs/ folder
• Publish only docs/ via GitHub Pages

This gives collaborators and instructors a clean public URL pointing directly to your results.

Method 1: Manual Setup via GitHub Settings

This approach uses the GitHub website — no terminal required.

Step 1: Push your HTML file(s) to the repo

Make sure your output file (e.g. docs/index.html) is committed and pushed to GitHub.

Step 2: Open repository Settings

1. Go to your repository on GitHub
2. Click the Settings tab (top right of the repo page)
3. In the left sidebar, click Pages

Step 3: Configure the source

1. Under Build and deployment, set Source to GitHub Actions (the modern approach)
2. GitHub will suggest a workflow template — click Configure next to Static HTML
3. A YAML file is shown in the editor. Scroll down and click Commit changes

Step 4: Choose your folder (optional)

If you want to publish only a subfolder (e.g. docs/), edit the workflow YAML before committing. Find the path line under the upload step and change it:

- name: Upload artifact
  uses: actions/upload-pages-artifact@v3
  with:
    path: './docs'   # <-- change this to your folder

Step 5: Find your URL

After the workflow runs (usually under a minute), go back to Settings → Pages. Your live URL is displayed at the top of the page.

Method 2: Let a Coding Agent Do It

You can ask a coding agent (like GitHub Copilot in VS Code, or Claude Code) to set up GitHub Pages for you using the gh command-line tool. This is faster and avoids navigating the GitHub UI.

Step 1: Ask the agent to install gh

Open the chat with your coding agent and paste this prompt:

Step 2: Ask the agent to enable GitHub Pages

Once gh is authenticated, give the agent this prompt:

The agent will typically:

1. Create (or verify) the output folder
2. Generate a .github/workflows/pages.yml workflow file
3. Run gh api commands to enable Pages on the repo
4. Commit and push everything
5. Report the resulting URL

Step 3: Verify the deployment

Ask the agent to check that the deployment succeeded:

The GitHub Actions Workflow File

For reference, here is the standard workflow that both methods produce. It lives at .github/workflows/pages.yml in your repo:

name: Deploy 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:
  deploy:
    environment:
      name: github-pages
      url: $
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

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

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './docs'    # change to '.' to publish the whole repo root

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Change path: './docs' to any folder you want to publish, or use '.' for the entire repo root.

Quick Reference