The Meta Post

Posted on July 26, 2012

These days, it seems like a new blogging platform pops up every week. I can think of Blogger, Tumblr, Weebly, and Posterous just off the top of my head. This blog uses none of those services. Instead, I’ve opted to generate and edit the raw HTML/CSS/Javascript myself.

Why would anyone want to do that? Well, I could answer half-heartedly that I want more control over my site than those services are willing to provide or ask, rhetorically, what would happen to all of my precious blog posts if the service I used suddenly went out of business and shut down, but truthfully, I just like being able to tinker with my site.

Maintaining this site “by hand’’ is actually fairly easy (and cheap). People have written some great tools that go a long way towards making it a pleasant experience. I use:

  • Octopress
  • Jekyll
  • Git
  • Markdown
  • Heroku

Let’s dwelve under the hood a bit to see how these tools power my blog.

Markdown Generates HTML for You

To state the obvious, nearly everything shown in this blog is ultimately rendred from HTML. But handwriting HTML is an enormous pain. Nobody wants to be constantly hitting <p> and </p> all the time just to write a new paragraph.

Markdown makes producing HTML a lot easier. It’s kind of like LaTeX in that it separates the content from the presentation. You mostly write naturally, with a little bit of special notation for special markup like inserting links or starting a list, and Markdown converts your specially notated text to HTML. Whereas LateX is great for producing PDFs, Markdown shines at generating HTML; and whereas LaTeX is great for formatting equations, Markdown is great for formatting blog posts.

For example, this snippet,

{% highlight markdown %} Markdown banishes WYSIWYG editors!

  • Bulleted lists begin with - signs.
  • Links are formatted like this
  • Italicize words by underscoring them. > You can also block quote!

Begin new paragraphs as in LaTeX: by skipping a line. {% endhighlight %}

is formatted by Markdown to look like:

Markdown banishes WYSIWYG editors!

  • Bulleted lists begin with - signs.
  • Links are formatted like this
  • Italicize words by underscoring them. > You can also block quote!

Begin new paragraphs as in LaTeX: by skipping a line.

I love how easy it is to read Markdown formatted text. Much better than HTML.

Powered by Octopress + Jekyll

A website/blog is more than just the collection of (Markdown generated) HTML files. Among other things, a blog requires 1. a way of routing URLs to the correct blog post and 2. a templating system for inserting a navigation bar and footer on every page. Jekyll is a tool written in Ruby that takes care of all that for you.

Jekyll itself is highly configurable and can have something of a learning curve. Also, it doesn’t come with a default HTML/CSS theme that lays out and your site and makes it look nice. Enter Octopress, a pre-configured Jekyll setup that takes care of 90% of the configuration, HTML layout, and CSS theming for you.

Every time I write a new post, I simply run the Rake task included in Octopress to completely generate all the HTML and CSS.

Free hosting by Heroku

Hosting static files is cheap on Heroku. For the (low) level of traffic I get, its completely free.

Version Controlled in Git

A major selling point of my setup is that, since all the content, configuration, and layout are in text files, I can version control everything in Git.

If you’re unfamiliar with version control, think back to when you wrote a major paper and saved multiple versions like ‘MidtermPaper,’ ‘MidtermPaperEdit,’ ‘MidtermPaperEditFinal’ to keep around earlier versions that you may want to revisit. Then imagine attaching your paper in an email to your friend Jack for proofreading. After Jack’s proofreading, you’ll have a ‘MidtermPaperEdit_jack’ file too. Version control tools like Git organizes this chaos. Git makes it easy to see previously saved versions and merge in other people’s edits.

I can’t stress how much better writing is with version control. After working as a software engineer for a year, I feel visceral disgust if the output of any work I do can’t be put under version control. (I’m looking at you, Microsoft Office.)