Publishing to GitHub Pages

Publishing to GitHub Pages#

What is GitHub Pages?#

GitHub Pages is a free static site hosting service provided by GitHub. It serves HTML, CSS, and JavaScript files directly from a repository, making it an easy way to publish documentation, portfolios, or project pages to the web.

Key features:

  • Free hosting for static content

  • Custom domains supported (or use <username>.github.io/<repo-name>)

  • Works with private repos — you can keep your code private while making the Pages site public

  • No server-side code — just static files (HTML, CSS, JS, images)

In this course, we use GitHub Pages to publish analysis results and project outputs, giving you practice with a common workflow for sharing research deliverables.

Publishing a Static Site#

Follow these steps to publish any HTML file (an exported Jupyter notebook, a Sphinx build, a hand-written page, etc.) to GitHub Pages.

Step 1: Create or Export Your HTML#

Generate the HTML you want to publish. A few common sources:

  • Jupyter notebook: In VS Code, click the “…” menu in the top-right corner of the notebook, then Export > HTML. In JupyterLab, use File > Save and Export Notebook As > HTML.

  • Sphinx / MkDocs / Quarto: Run the build command and grab the output directory.

  • Plain HTML: Write it by hand or with a template.

Name the file you want to be the landing page index.html.

Step 2: Set Up the ./docs/ Folder#

In your repository:

  1. Create a docs/ folder in the repo root

  2. Place your index.html file inside docs/

  3. Create an empty file called .nojekyll in docs/

The .nojekyll file tells GitHub not to process your files with Jekyll (GitHub’s default static site generator). This is important because Jekyll can interfere with certain file names and paths (e.g., files or folders that start with an underscore).

Your folder structure should look like:

your-repo/
├── docs/
│   ├── index.html
│   └── .nojekyll
├── src/
│   └── ...
└── ...

Step 3: Commit and Push#

git add docs/
git commit -m "Publish site to GitHub Pages"
git push

You can also do this using GitKraken, VS Code’s Source Control panel, or GitHub Desktop.

Step 4: Enable GitHub Pages#

  1. Go to your repository on GitHub

  2. Navigate to Settings > Pages

  3. Under “Source”, select Deploy from a branch

  4. Set Branch to main and Folder to /docs

  5. Click Save

After a few minutes, your site will be live at:

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

Note: Your repository can remain private. Only the GitHub Pages site will be publicly accessible.

Tips and Gotchas#

  • First build can take a couple of minutes. If your site 404s right after enabling Pages, wait and refresh.

  • Cache is aggressive. When you push updates, do a hard refresh (Cmd+Shift+R) to see changes.

  • Use relative paths for any images, CSS, or JS in your HTML so the site works under the /<repo-name>/ subpath.

  • Check the Actions tab on GitHub — Pages builds show up there, and failures will tell you what went wrong.

Contents