Chris Bugg

2 - Reneging

Welp, my "hand-crafted, artisanal, free-range HTML" didn't even last a week. As I was writing up my previous (and first) post, I went looking for the link to GitHub Pages. When the page loaded I saw the big GitHub logo at the top and it hit me that I'd been mis-capitalizing 'GitHub' as 'Github'. To make it worse, although I only used GitHub twice in that post, I had it at least once on each page in the header. This could easily be solved by a grep or sed, however I realized that if I were to keep making blog posts, the small tweaks and even larger changes would start to add-up. I needed a better plan.

I figured I had three real options to do something better:

1. DIY Bash/Python script as a Static-Site Generator

   Basically write up a simple little script that just does what I need: glue a common header and footer section onto some body sections. This would be fairly quick, wouldn't require dependencies, would show off a bit of my scripting ability, but wouldn't be able to handle almost any edge case.

2. Use an existing Static-Site Generator

   This would be something like Jekyll/Hugo where I install it, spend some time configuring it, then throw a Markdown file in the mix and hit go every time I need a new post. It would take some time to set up on my machine (as compared to something like Bash/Python) and would need food, water, and regular updates. It might also be difficult or slow to throw out the default theming to just have it do what I'm looking for. It would give me a ton of power and flexibility once I had it set up, and publishing new posts would be a breeze with Markdown.

3. DIY PHP as a Static-Site Generator

   This is the most overpowered, wrong tool for the job. This odd solution likely came to mind because I've done it before, though on a project that already needed server-side functionality. The short of it is that you throw all your common HTML/CSS bits into a PHP file as functions, then throw those functions in your pages where you need all that common HTML. This solution ends up being problematic because, arguably, this isn't what PHP is really designed for or around. It also can be quite problematic performance-wise because if you don't have any sort of cache-ing or other performance tuning you need to run every request through the PHP interpreter. This adds unnessessary overhead (in every dimension) to every request, which will add up to a less performant, more expensive site to view and run. On the plus side, if I wanted to add a database and some dynamic content, I'd be all-set!

I went with #1, DIY my own small site-generator script. Though it probably would have been easier for me to write-up in Python, I decided for Bash. Bash seemed more appropriate for this, as it is mostly file-management in a Linux environment.

Starting off I re-organized the folder I keep all this in into a directory with 4 things at the base (for now).

• ./generator.sh - The hot new script I would write that would re-build the site every time it was run
• ./parts/ - The directory where I would keep all the modular parts and pieces used to build the site
• ./site/ - The destination folder that generator.sh would build to
• ./old/ - A nice safe archive for all the old assets and stuff should I ever want or need them

Next up I split out ./parts/ into:

• ./parts/assets/ for the standard assets, ie: header/footer
• ./parts/pages/ for the non-standard things, ie: body sections

Then it was finally time to get to writing a script. My initial idea was that I would iterate through every page in ./parts/pages/, touch a new file of the appropriate name and in the appropriate place under ./site/, then append all the pieces (header, body, footer) and move onto the next. Sadly I got stuck trying to figure out how to get a good handle on the 'old' file's relative position, in order to figure out the relative position the new file needed to be created in. I figured I could do something like cut up the path and grep through the parent folders, but that seemed like a terrible hack. Thankfully I realized I could solve things a lot easier by just cp-ing the pages over and editing them in-place.

In lieu of going through each line of the script here I heavily commented it (much to future-me's delight) and have posted it on my GitHub. It really ended up being very simple and straight-forward, though I'm already thinking about splitting up header.html to have a seperate head.html....

I think this was a nice change that should pay future dividends, and am looking forward to what other changes will be in-store for this little blog!

Happy Hacking!
- Chris