I’ve been wanting to start up a new blog for a while, now. I was thinking maybe I’d do an art blog, or perhaps an engineering blog. At the very least, someting a bit more focused and presentable to the general public. When it came to thinking about how to publish the blog, though, it became clear that dealing the blogging platform was one of the biggest obstacles to actually doing it. I’ve typically used WordPress in the past, but over time it has become apparent that it has some limitations that make blogging more difficult than it should be. I’ve never really had success finding a theme I feel good about; and once the site is up, I have to deal with an endless barrage of spam comments that somehow make it through the Akismet spam filter even though they have a gazillion links in them or are selling pharmaceuticals.
So, when thinking about starting this blog, the first task was to figure out what platform I wanted to use. I was ready to try something besides WordPress. I had met Kyle Mathews, the guy who founded Gatsby, which is a static site generator that has surged in popularity, and I had been hearing about people using Netlify and Gatsby to create a static blog, so that’s where I started. That, however, was only the beginning of the journey. The platforms and tools I decided to use shifted multimple times, ultimately landing on just writing a small static site generator of my own. Here is how it happened:
Journey through Static Site Generators
Gatsby + Netlify CMS
A hot combo right now for creating blogs is Gatsby (a static site generator) and Netlify (a hosting service for static sites). I already pay for a hosting plan elsewhere, and the content management system that Netlify uses, Netlify CMS, can be used independently of their hosting sevice, so I thought I’d try setting up a site that uses Gatsby and Netlify CMS, and runs on my existing hosting service. The main sticking point here was the learning curve for Gatsby. If you build your site using Gatsby, you get a lot of things, including a simple way to build interactive web pages that are fast and search-engine-friendly, which is typically not a simple problem. It also does some fancy things to make pages load very fast. However, if you don’t need these things, and you’re new to Gatsby, then the cost of getting up to speed on that platform may not feel worth it, as it was with my case. That launched me on a journey to see if I could find a static site generator that was a bit simpler.
Hexo + Netlify CMS
There are a lot of interesting static site generators out there. Hexo is a popular one, and it’s even targeted at blogging; however, creating a theme for a Hexo seemed to require a lot of configuration file wrangling, and as far as I could tell, templates didn’t get custom metadata in posts passed to them, making the whole system less flexible than I would have liked.
Custom Site Generator + EJS + Netlify CMS
After looking at a few other static site generators, I started to realize that the core problem they solved was a very simple one: pull data from somewhere, and generate web pages by passing that data into templates. I built a minimal static site generator with ~250 lines of TypeScript code, SimpleSiteGen. EJS was the template language that Hexo uses, and I liked it enough when I was using Hexo that I decided to keep using it for my own site generator. After a while of building EJS, though, I began to run into some hurdles. One of those was the rather unhelpful error messages it produces when it encounters a problem. I got stuck trying to figure out why on Earth EJS was failing to process my template, when I decided it would be a good idea to look for another template solution.
Custom Site Generator + JS Template Strings + Netlify CMS
Fortunately, there’s a cool JavaScript feature that became part of the ES6 standard called Template Literals which can essentially act as a template language. A template is basically anything that consumes data and returns text, so you can create a JavaScript module that acts as a template just like the one that generates the footer for my page with the copyright info:
module.exports = data => `\
<div class='pagefooter'>
<div>© ${data._site.author}</div>
</div>
`
Custom Site Generator + JS Template Strings
I eventually got my site up and running on my hosting provider, at which point I realized that although Netlify CMS was working fine while hosted locally on my computer, when it was running from my server, it couldn’t authenticate with GitHub, (which it uses to store all of its content,) without some extra work. I was using Netlify CMS to write articles because it had a nice interface for adding metadata to posts, and its editor was more of a WYSIWYG editor than other markdown editors I tried, but it was far from essential. Rather than trying to get Netlify CMS to work, I decided I’d just keep an empty post template around to easily create new posts with the proper metadata fields, and write articles using any old markdown editor. So far, I’ve used both VS Code and the GitHub web editor for writing posts, and both do reasonably well!
So, now I write my blog posts in markdown using either VS Code or GitHub, and when I want to publish one, I set the “publish” metadata value to true, and push the changes to my git repository. One other piece of this worth mentioning: GitHub has this awesome feature where you can set up web hooks, which causes GitHub to send information to a URL any time a change is pushed to the repository. I set up a script on my blog site that will pull down the latest changes from GitHub and rebuild the site, and then I set up a web hook in GitHub to make a request to that script any time a change is pushed. Now, I don’t have to touch my site at all to publish new content. Once it’s checked in to GitHub, the rest is automatic!
Conclusion
My site generator may not have all the features that other site generators provide, but what it has going for it is simplicity and complete freedom to customize. The site itself is definitely a work in progress. You may notice that there are no categories or tags, and no ability to comment on posts. It has basically the minimal requirements for a blog site, but I’m planning on eventually getting around to those extra features, and I can still get started without them.
This is a companion discussion topic for the original entry at https://saltytron.com/posts/2020-05-24-what-this-blog-is-made-of/