Pertinent Resources

This section simply tabluates the posts and documentation used to effect migration of all sites from the Grinnell College static host to GitHub Pages.

Customizations

Do NOT Set publishDir = "docs"

Do NOT change the publishDir parameter in your configuration, if you even have one! The default public setting is correct.

gh-pages.yml

Host on GitHub directs us to create a new .github/workflows/gh-pages.yml file in each project. This file directs GitHub to build a Hugo site each time a triggering event, like a “push”, takes place.

The document specifies the following contents plus a few additions of my own:

name: github pages

on:
  push:
    branches:
      - main  # Set a branch to deploy
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - uses: szenius/set-timezone@v1.0  # per https://github.com/marketplace/actions/set-timezone
        with:
          timezoneLinux: "America/Chicago"

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

GitHub Pages Settings

It’s not documented well, but important to note that this workflow will create a new gh-pages branch of your repo and the root of that branch is what you should publish! Pay attention to those settings in the figure below!

To complete the process of creating a GitHub Pages site you’ll need to visit your repository’s GitHub Pages Settings page and make selections like you see in the figure below. The example below is taken from https://github.com/Digital-Grinnell/Digital-Grinnell.github.io/settings/pages.

Completed Migrations

And that’s a wrap. Until next time…