Alex's Home Page

Blog Tech pt.1

...a quick look at the tools I've used to build this blog

While most of my posts will deal with more abstract "builds" (businesses, processes, campaigns), this one is more of a how-to on building a blog like this one. This blog is not a WordPress or Drupal site. Those CMSes are nice, as long as you like managing a server filled with dynamic content through a clunky interface. Security updates, software updates, server updates, php screw-ups... all of these things waste your time and effort. They provide some cool features, to be sure, but how many of those cumbersome baked-in tools do you need when you have a good understanding of some command-line tools, liquid (or mustache, or what have you) templating, and HTML/CSS/JavaScript?

The answer, as it turns out, is not that many. And that's why this blog is built on Jekyll, a "blog-aware" tool for building static, templated blogs.

It might not be the pinnacle of programming prowess or design, but I like the simplicity of this set-up, and I hope that you do too.

Before I get to the set-up for this page, what features do we really need in a simple blog? Here's what I wanted, in order of importance.

  • The ability to write posts anywhere in simple text format. No internet connection? No big deal, as long as offline files can be written in a format that can be converted into posts later.
  • Static serving of data. Only one Apache server, no databases of former posts, no PHP.
  • An intuitive directory structure.
  • Simple templating and themes.
  • Customize-able post presentation (archives, breadcrumbs, previews, etc.)

And that's it. The first two points are especially key, since logging into a CMS dashboard can get really old, really fast. It can get old almost as quickly as debugging php errors between a SQL database and front-end content. And so, we use Jekyll.

Jekyll is extremely simple to install, as long as you have a bit of familiarity with a terminal interface. You'll need to be comfortable moving around the directories in your site using cd instead of clicking a folder icon. But that's OK... using computers is just like reading. Leave the pretty pictures to the kids, because adults use words. (See this incredibly useful site for the source of that quote.)

Jekyll works by "baking" templates, HTML/CSS, scripts, and markdown files into a static presentation of your blog posts. This baking can be done in any environment, but I've taken a liking to the workflow provided by cloud-based IDEs like cloud9. As a sometimes-Chromebook-user, I like having access to a full linux server whenever I need it, but you can do all of this work with Jekyll on your own machine at home, too. In the case of this blog, all I had to do was fire up a terminal, cd into the blog sub-directory and enter:

~ $ gem install jekyll
~ $ jekyll build
~ $ jekyll serve --port $PORT --host $IP

This is also in the specific case of serving a Jekyll blog in a single sub-directory of a static site. I could also have built the entire site using Jekyll and still served the static pages (e.g. "about me"), but that seemed like overkill, since I would have to keep any locally-hosted previews running at all times if I wanted real-time updates. Either way works, so I went with a bit of separation between blog and page.

Also of note: if you're running this site on a local machine instead of on a cloud-based environment or an external server, then there's no need for the --port $PORT --host $IP bit, as those are Jekyll flags being used to pass in cloud9-specific variables.

The above commands (starting at jekyll build) will also only work if you have the correct directory structure, with special importance given to the _config.yml file (see the docs on _config here). Take a look at the link on proper directory structure above. You'll notice a couple of things:

  • Good 'ol index.html hanging out in the root directory. This will be the place where everything is smushed together and presented to the browser to display.
  • A lot of directories (and one file) with the naming format _name instead of just name. Anything without the underscore is included as-is in the final _site folder (more on that later), whereas anything with an underscore is just a component to be used to build the final index.html files at the bottom of every directory.
  • A mix of file extensions, from *.txt to *.html to *.md to *.yml. Jekyll takes all of these files and turns them into cool stuff.

I'll save the meat of the explanation of how everything ties together for my next post on the tech behind the blog. For right now, though, it's enough to know that all of the _posts files are written in Markdown format, saved in with a naming convention that excludes capital letters, replaces spaces with hyphens, and includes the date in year-month-day- format at the beginning of the title, and that that information, combined with some of the front-end matter (more on that in the next tech post) allows Jekyll to build the final output into an index.html file that sits in a series of directories created according to the naming configuration outlined in _config.yml.

And after it's all said and done, and you've run jekyll build on your final product, Jekyll spits out a _site folder. That folder contains everything that needs to be uploaded via SSH or SFTP to the server. With SFTP, all you have to do (once you've figured out how to connect to your web host from the command line) is use put -r [directory or file] on all of the contents of _site, and you're ready to go.

And that's an introduction to getting a static blog up and running using Jekyll. In the next post, we'll talk about how the theming structure works and look a bit deeper into using Liquid Markup to create some of the neat blog features that we might miss from traditional blogging frameworks.