how this blog is created
keeping things simple
having recently spun this site up, i thought it might be good to talk about the blogging setup i’ve settled on over the past few years. i didn’t really have any strong thoughts or opinions on this up until about a year ago but now i think it might be useful to share not just how i’m doing things, but why. ultimately, i’m not doing anything special or groundbreaking, so before i get into the technical details (which will probably be pretty short) i’ll talk a little bit about the why.
i started my first blog around the same time that github pages was becoming a thing and it was through that that i found jekyll1. i kept that blog hosted on GH pages for a few years before deciding i wanted more flexibility with what i could host and ownership over my data, but one thing i knew i wanted to keep was jekyll: writing in markdown feels natural and intuitive, it only requires a couple of dependencies, generating static sites means i never really have to worry about administration or security, and i could use vim to do all of my writing. thankfully, moving a jekyll site is probably as easy as it gets since there’s a single directory that defines the entire site and the markdown files can be quickly rendered to html using different styles and theming. so that turned out to be pretty painless.
i’ve now kept that blog running for a number of years with minimal effort and have come to really appreciate the benefits and simplicity this system has provided. hosting options are basically endless since its all just html and css, so migrating between platforms is usually straightforward.
tl;dr:
- markdown-based: everything should be markdown. fight me.
- portable: not tied to any particular platform or tech stack
- minimal effort: self-hosting and data ownership all sounds great until you realize it means being responsible for keeping everything running. this solution gives me control+ownership with minimal effort.
- easy backups: i want to be able to keep my writing around for a while, so making backups and data transfer painless ensures it actually gets done.
now into the details for this blog.
building
the static files are built using jekyll and i’m currently using the “no style, please” theme. as i said before, there’s really nothing special i’m doing with this blog right now so building it from scratch on a new system is as simple as:
git clone <blog-repo> && cd <blog-repo>
bundle install
bundle exec jekyll build
hosting and deployment
i’m currently using google app engine to host my blogs as it provides a super easy way to push static files and have them served without having to keep a compute instance running 24/7. additionally, the site automatically gets SSL and i can get a free google-managed cert if i want to use a custom domain.
below is the app.yml that defines the entirety of the app deployment. all it does is upload the
contents of the _site/ directory produced by jekyll to gae.
runtime: python37
handlers:
- url: /
static_files: _site/index.html
upload: _site/index.html
- url: /(.*)
static_files: _site/\1
upload: _site/(.*)
note: this particular hosting method does have some limitations and does require some extra work if you want to use permlinks that don’t map directly to static files (i.e. /blog vs /blog.html).
customization
adding customizations to existing jekyll sites is also pretty easy (for the most part). generally its just a matter of overriding specific styling files for the theme that’s being used (for gem-based themes). i’ve just gotten into the habit if cloning the repo for whatever theme i’m using and keeping a full local copy of it that i can tweak directly. this may mean i eventually have to manually update dependencies or just rehome the post files to a new clone of the theme if things end up breaking at some point but so far i haven’t had any issues.