Setting up a hugo static site hosted with Porkbun

Content generation

This is a static site generated with hugo with the PaperMod theme. I wanted an easy to use static site generator. I considered Jekyll and believe it to be a good choice for static sites. There seemed to be slightly more themes I liked with hugo so I went with that. That's a pretty superficial choice but I also don't plan on hacking on the site generation itself so I was agnostic to the Go versus Ruby choice.

Domain hosting

This site uses porkbun for a domain host. I chose it not least because I do enjoy porkbuns. They also listed static site hosting as a service which suited this site well.

Porkbun link-in-bio versus static hosting

By the time I wanted to host this site, I either made the choice without remembering or it is a default setting to have new sites use the "link in bio" hosting plan (which is free). But I need to pay their small fee to host a static site. I then found porkbun's helpful FAQ, which helped me change out of link in bio mode to static hosting mode.

Github Integration

If you don't want to upload your files directly from your computer Porkbun offers GitHub connect to automatically publish changes to the site. But I had some confusion about how the generated site should sit in the directory structure. The integration let's you pick a repository and a branch on that repository to watch.

File structure Porkbun expects

I first chose main, but the integration didn't appear to work. The issue I think is the strucuture of the files for the static site that Porkbub accepts. By default hugo exports the generated static files to a directory public. The file hierarchy roughly looks like the following after you create a new project and render the files:

. ├── archetypes │   └── default.md ├── assets │   └── css ├── content │   └── posts ├── data ├── hugo.toml ├── i18n ├── layouts ├── public │   ├── 404.html │   ├── assets │   ├── categories │   ├── index.html │   ├── index.xml │   ├── page │   ├── posts │   ├── sitemap.xml │   └── tags ├── static └── themes  └── PaperMod

. ├── archetypes │   └── default.md ├── assets │   └── css ├── content │   └── posts ├── data ├── hugo.toml ├── i18n ├── layouts ├── public │   ├── 404.html │   ├── assets │   ├── categories │   ├── index.html │   ├── index.xml │   ├── page │   ├── posts │   ├── sitemap.xml │   └── tags ├── static └── themes  └── PaperMod

Enter fullscreen mode

Exit fullscreen mode

We can see that the public directory contains all the files and directories for the site.

Some other static file hosting servies let you point to a directory that contains the files for the static site, but it appears that Porkbun expects that these files be at the root of the github repo and branch you point it. Rather than overwrite main to just have the contents of public we can create another branch that contains only what we need.

Setting up a deploy branch

I had Claude generate a github action to create the generated files in a different branch deploy. Something like .github/workflows/deploy.yml

name: Deploy

on: push: branches:

• main

jobs: build-and-deploy: runs-on: ubuntu-latest permissions: contents: write steps:

• uses: actions/checkout@v4 with: submodules: true

• name: Setup Hugo uses: peaceiris/actions-hugo@v3 with: hugo-version: 'latest'

• name: Build run: hugo --minify

• name: Deploy to deploy branch uses: peaceiris/actions-gh-pages@v4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./public publish_branch: deploy force_orphan: true`

Enter fullscreen mode

Exit fullscreen mode

Then I set the branch to watch to deploy in the porkbun UI and that did the trick. There were a few error messages but it seemed to not matter because now you are reading this and so it worked.