Building Websites with Icecake

Published 2016-04-04

I recently used Icecake to rebuild my site from scratch. Icecake is a cool and easy tool for building static websites. And actually, I just wrote Icecake from scratch too, because I was unhappy with other, similar tools I tried.

But more importantly, Icecake (or your own version of it) is the way everyone should be building websites, whether you're building a personal blog or a the homepage for a Fortune 500 company or a state agency.

Static Websites

It's like we're going back to 90's.

Let's pause for a moment and talk about what it means for a website to be "static" and why you should be doing it this way.

"Static" means that your entire site is flat HTML files. There is no content management system. No database. No security vulnerabilities. No need to update the code. No need to create usernames and passwords for people to login. No way to login.

When I described static sites to a colleague of mine he said, "It's like we're going back to 90's." Yes. Exactly. Let's go back to the 90's -- to simpler times before security vulnerabilities made headlines every other week.

Life with static sites is awesome. They just work. They stay online, basically forever, with absolutely no effort whatsoever. They scale from 1 user to 100,000,000 users. They're completely secure. You can back the entire thing up in GitHub or Dropbox in 2 minutes. You can host them on Amazon S3 for pennies a month.

Anatomy of A Site Builder

A static site builder is a very simple program at its core.

  1. Collect all of the input files (usually markdown or partial html)
  2. Pass them through a renderer to turn them into full HTML with headers, menus, and other common layout components
  3. Write them to the output folder with the .html file extension
  4. For extra points the tool will automatically rebuild the site (or a page) when you edit a file.

That's it! Now you're an expert.

Prior Art

As it turns out I'm not the first person to discover that static sites are awesome. Tom Preston-Werner, one of the co-founders of GitHub, also built a static site tool called Jekyll back in 2008. It's now the most popular tool of its kind. It's great. You should check it out, especially if you like programming in Ruby.

I've used Jekyll, Octopress, Pelican, and Hugo. A few years ago I wrote a another static generator using Symfony components and Twig which was designed specifically for developing internationalized websites.

There are lots of these tools. So why write a new one?

It's All About Flow

I want a blogging tool that fits my workflow, not one that I have to change my workflow to use.

When I sit down to write I want to focus on my prose, not the blogging tool. Right now I'm writing in Sublime Text, my favorite text editor, where I write all of my notes and articles. I write everything in Markdown. I sometimes include source code in my notes and articles, and I check everything into git and store it on GitHub.

My workflow works great for me. I want a blogging tool that fits my workflow, not one that I have to change my workflow to use.

All of the blogging tools I mentioned above came with various problems. Keeping Octopress up-to-date is super tedious. Converting my site to Hugo was painful. Go templates suck and building a site with Hugo involves a lot of really convoluted magic behavior managed by config files (where a few lines of code would suffice).

Also, a lot of these projects have grown really complicated. Hugo, for example, is 24,000 lines of code using cloc (not including any dependencies).

It's time consuming to peek under the hood and change something, and all of these things are a distraction from writing content for my site.

So what are we really after?

About Icecake

Icecake is very simple. All of the logic is in one file -- currently around 700 lines of Python (including comments). It uses some very well-designed libraries which make the whole thing really pleasant to use and work on.

Icecake uses Jinja templates. Jinja is a beautiful templating language that you have probably already used before if you've used the Flask micro framework for Python. Jinja is the best templating language I've ever used (and I've used a lot of template languages -- smarty, erb, mustache, handlebars, jsp, twig, django, and more).

Icecake uses Markdown for authoring articles. Markdown is everywhere these days, from GitHub to Stack Overflow, so I assume you're familiar with it already. And Icecake also uses Pygments to add nicely-formatted source code to your articles. Pygments used to power syntax highlighting on GitHub until they rewrote it in Ruby.

There is no JavaScript required to make any of the features work, and the syntax highlighting requires only about 40 lines of CSS. This lightweight core means your site will be fast (even on a slow mobile network), easy to cache on a CDN, and you can deploy it to just about any web hosting platform on the planet (even ones that have been around since the 90's).

Icecake has three modes of operation:

Icecake also sports a very simple but powerful query mechanism that lets you create arbitrary series of articles, lists of articles by tag, or lists from folder hierarchies very easily.

And that's about it. I've tried to avoid a lot of common but crufty features. No themes. No plugins. No options. No configuration file. Just one core featureset that works.

Make Icecake Yours

Icecake should start easy and stay easy forever. A lot of things pick up uncessary features as they go. My goal with icecake was to build a very minimal, very lightweight core for a site builder that satisfies the bare minimum features for building a site.

This is done! The rest is up to you.

Your site's theme is not part of the site builder so icecake doesn't touch that. Just bring your own! If you want to do some crazy stuff with Angular.js or D3.js icecake can do that. If you just want simple HTML icecake does that too.

There are other really cool features that could be added in just a few lines of code. For example, you could make icecake read strings from a localization file and build a website in 10 languages. I don't think most people need that feature (and I personally don't need it) so I didn't write it.

If there are other features you really want for your own project you can probably add them in only a few lines of code.

Icecake is licensed permissively under the MIT license so you can customize it and share your changes, or keep them to yourself, or use it to build a business.

If you use icecake and love it, hate it, or find something that doesn't work I'd love to hear from you. Enjoy!

Related

icecake python