Hugo, GitHub Pages and Let's Encrypt

Create a new Hugo site.

hugo new site hugo
cd hugo
git init

Add a theme. I cloned it, rather than adding it as a submodule, as I plan to modify it.

git clone https://github.com/koirand/pulp.git themes/pulp
rm -rf themes/pulp/.git

Install the example configuration file.

cp themes/pulp/exampleSite/config.toml .

Remove the archetype-folders, they seem to be causing issues on GitHub actions (?).

rm -rf archetypes/
rm -rf themes/minimal/archetypes/

Start the development server and test that it works. The --navigateToChanged will automatically navigate to posts as you edit them.

hugo server --navigateToChanged # add -D to show drafts

Add the following GitHub action for deploying to gh-pages. This is the GitHub actions example for hugo, verbatim, though I don’t really need the submodule stuff.

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

      - 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

Create a GitHub repo. Exclude the server lock files from git.

echo '*.lock' >> .gitignore
git add .
git ci -m "first"

Add the rest of the files and push.

git remote add origin <your repo url>
git push

Enable GitHub Pages from the gh-pages branch of the repository, from the /<user>/<repo>/settings/pages url on github.com.

I use Cloudflare to manage my DNS. To set this up, change the name servers on your domain provider’s website to point to the two following Cloudflare name servers

carla.ns.cloudflare.com
jimmy.ns.cloudflare.com

Then add your domain in the Cloudflare UI to manage the rest of its setup from there.

Add the following A records for your domain as explained in the GitHub docs for custom domains. My domain is torgeir.dev, so I added four A records in the Cloudflare UI, making torgeir.dev point to each of the following

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Also add a CNAME record for www.torgeir.dev, with the following value, where <user> is your GitHub username. You need this entry even if you don’t plan to serve content from the www.torgeir.dev subdomain, but instead plan to use the apex domain torgeir.dev

<user>.github.io

Back in your GitHub repo, create a file static/CNAME with the value of your domain, e.g. like this

torgeir.dev

Add the file to git and push it to make GitHub deploy your site on GitHub Pages.

If you own a .dev domain, this should do it, and Google’s star certificate for your domain will work for all subdomains from here on. Go back to the GitHub Pages settings and add your domain in the Custom Domain section!

For domains other than .dev, you can make GitHub + Let’s Encrypt provide a certificate for you. To make this happen, also add a CAA record in your DNS suppliers settings with the value

letsencrypt.org

Then go back to the GitHub Pages settings, add your domain in the Custom Domain section and check Enforce HTTPS. You only need to check this if your domain is not a .dev domain. Let’s Encrypt and GitHub will create and serve a certificate for your domain, and your GitHub pages Hugo site will be served on https!

🔐👌

Edit: Later, I found and switched to the theme heksagonnet/piko which I aim to wield into something of my own.