index about contact

Getting github pages to work with my custom site generator

So, I built a crappy site generator. It's pretty bad, which is the result of some very targeted design decisions:

Feel free to look at the code (linked above) if you want, but it's really the least interesting part of this post. At a quick summary, here's what it can do:

Getting Github actions to deploy from my own generator

I hasten to note this is by no means revolutionary or new. But here's how I did it.

Github Pages comes with Jekyll site generation built in. This is nice, unless you want to use your own generator.

Now of course, you could generate it locally and push it, but really, where's the fun in that? So, let's get github to do all the work.

For reference, here is the action that builds the site. At a high level, it:

  1. Generates the site from the files in the repo
  2. Resets to the www branch, which contains the built output served by GitHub pages (you can change the branch it watches in settings)
  3. Checks out and adds files
  4. Makes a new commit postfixed by the actions run number
  5. Pushes to the www branch.

(Note to readers: I haven't gone through this with a fine-tooth comb. It's quite possible that the reset is entirely unnecessary.)

The fantastic GitHub Push Action by ad-m was instrumental in getting this to work so easily.

The end result

So what am I left with?

Seems like it fits the bill! I'm happy with the output, and maybe I will spend some time improving the code to something I would be proud to show to people, but the fact remains: working code that solves the problem is better than neat code that doesn't work yet.


Follow the discussion on Hacker News

Posted 2021-01-17

The Documentation Triangle →