How this site works

Last modified at 2020-09-06 17:08:38 +0000

If you’ve ever looked for free ways to blog, you may have come across Jekyll (or GitHub Sites). Jekyll is an open-source blog framework that allows you to write posts in markdown. I use it on this site to render posts, including this one.

For many users, you can stop here. Jekyll has themes that make it easy enough to download and start writing with very few actions at all. All you needs to do is download a Jekyll theme and use GitHub Pages.

But what if you wanted more? What if you wanted the fastest blog – optimizing for content and security? You may not want to use the entire labor of pull requests when writing posts. Combining CloudFlare with open source GitHub actions can automate this entire process.

First – we construct the actual content. The site itself revolves around markdown (.md) files. These files contain front matter which specifies properties about them. For instance, blog posts contain a title, description, permalink, and tags. Jekyll processes these elements when deciding which actions to take on the site.

GitHub Pages (running Jekyll) transform the markdown into HTML files. We can define aspects of these files for the final rendered page, such as header and footer content. These changes, once configured, allow us to craft the final version of our site – the part the user sees. If we want to insert multi-media, we either include it in the repository or link to it elsewhere.

Then, we can take it a step further. GitHub actions are a recently released feature allowing for CI/CD style actions to run. Think of having a script run every time you submit a pull request, or commit new code. GitHub Actions allows for these triggers, and can use them to perform all sorts of behaviour. On my site, I run a series of static analyzers over each post. Once they have finished, assuming they found no issues, GitHub labels the pull-request. This pull request labeling allows me to know if I have to review it. If not, the pull request automatically merges, assuming I touched no sensitive content. We define what sensitive content here is in a YAML file (I include all JavaScript).

Next comes CloudFlare. CloudFlare for this site exists on the free plan. Because we host static content near exclusively, more powerful protections aren’t as useful. Using a WAF here is not very useful, because we have no user input at all. As the site has no concept of state, we do not worry too much about modifications made. CloudFlare Workers allow us to apply security headers when you visit the site. Changes to this configuration will eventually exist as Terraform code, also run through static analysis.

The end result isn’t perfect, but it suits me well. This setup allows for a performant and secure blog, with much room for configuration. Whether it be changing the content or setting up a system to tweet every time a new post is up, we can do that. Keep in mind – all technologies used here are free (as in beer). Now, whenever you wish to post to your blog, GitHub can handle it. All you will need is your account, which you should protect with MFA.

If you’d like to learn more, take a look at the colophon for this site. I list the technologies and repositories used in great depth, with open-source code.