sourceless

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:

• I didn't want to spend a huge amount of effort building it. This is for fun, not work. You're not going to find any unit tests or any significant refactoring effort.
• I want to generate a fast site that I can host for free (sans domain costs).
• I want it to be easy to author new posts in my tool of choice (emacs).
• Deploying the website should be a git push.

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:

• Fixed index page that lists posts and pages
• Pages and posts generated from markdown
• Page/post metadata stored as EDN (Jekyll-style, but EDN isntead of YAML)

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?

• A small, lean, html-only site
• On free hosting
• Using any site generator I want
• Pushing a new version to master auto-generates a new site

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