A Few Static Blog Generators
Before finally choosing an engine for my own blog, I spent too much time comparing the many available options. My goal in this post is to share what I learned about some of the tools that are avilable. Hopefully this makes it easier for others to publish their own writing.
Why Static?
Static website generators take content in a user-friendly markup language (e.g. markdown) and compile it into flat HTML pages.
Static sites, particularly static blogs, have become increasingly popular. This isn't to say they are for everyone. They do require more effort to setup and generally have fewer features than a mainstream blogging platform.
The reasons for the increasing popularity of static websites can be found all over the web. Here are some of the big ones for me.
Fewer Moving Parts
Simple websites shouldn't require the same stack as a full-blown web application. Why depend on an app server and a database when all you really need are flat files and a web server?
Cheap and Easy Deployments
Deploy your blog anywhere that can serve static assets. Some free/cheap options for this:
- Github pages (free)
- s3 (practically free unless you are famous or ddos yourself)
- shared host (at least you don't have to use their database)
- a tiny VPS (my choice)
Security
Having had to clean up hacked Wordpress installations, I know what a pain it is to keep Wordpress up to date and locked down. Any popular web app that can be deployed to your own server is a natural target for attackers. By serving static files on disk, we eliminate a wide range of attack vectors.
My Requirements
Having decided on a static blog, I still had a sea of options to sift through before I could reach a decision. Salient features include:
reStructuredText
Markdown is a very popular choice for web writers. While I do like markdown, I prefer reStructuredText for a number of reasons. It requires more upfront investment to learn its larger syntax. But its rich feature set is well worth it.
Some great rEST features are footnotes, tables of contents. Also, .rst files look great in plaintext (even without syntax highlighting).
Theming Support
Themes give you a big head start when starting a site. Taking an existing theme and customizing it to your needs is a lot faster than starting from scratch. Tools like twitter bootstrap make this process easier. But they don't save you from having to learn the the names of all of the template variables and settings provided by your static generator.
Good theme support depends on a well-designed site theme API to enable customization. But it also depends on a community who has already released themes worth using.
Extensible
Should I ever want to hack my own plugin or do some customization, I want to know that the engine exposes a good API for extending its functionality. For this reason, I considered only options written in Python, Ruby and Javascript: the three languages where I'm most comfortable.
Configurable
I should be able to tweak the most important features with a simple change to a settings file. Important options for me are the ability to use arbitrary URL structures and organize my content however I choose.
of Tool Fetishes
As would-be-bloggers, we are spoilt choice when choosing a static blog engine. We can start with many off-the-shelf themes and customize them to suit our needs.
That said, the choice probably does not matter as much as we like to think. The most important part of blogging is the content, not the presentation. It's not about the minor differences between blog generators. Nor is it reinventing yet another one. We reach a point when our obsession with our tools becomes fetishistic (MUST blog with vim!).
The tools that you use for publishing only matter if you write regularly. I would argue that we see the same fetishistic attitutude during perennial flamewars about text editors and web frameworks.
The past few years have seen colossal duplication of efforts in the space of static site generators. While no solution will suit everyone, more consolidation would be nice.
The winner is...
After almost going with Jekyll, I found Pelican. It is built on top of software that I consider best of breed:
Development is currently very active. Compared to the others, it has good documentation. I generally prefer Sphinx docs to the combination of RDocs and GitHub wikis popular among Ruby projects.
Pelican has a dedicated script called pelican-themes for managing themes. I liked the default theme enough to take it as the starting point for my design.
Its has a 'watch' mode for development has worked very well for me so far. Even when I left it running for long periods of time.
A few influential python bloggers have also switched over to Pelican.
Other Contenders
Here is a quick overview of the other choices that I evaluated before choosing Pelican. In some cases, my evaluation was fairly superficial. I won't try to be comprehensive. Instead, I hope this this will serve as a good starting point for someone trying to make the same choice.
Jekyll
Jekyll is the engine behind GitHub pages. It's written in Ruby and is easily the most popular of the options I considered. Its important enough that its creation may have helped to bring about the resurgence of static websites in general. As I mentioned it was my top choice behind Pelican and a well built piece of software.
Jekyll's large community comes with great benefits. Two popular projects built atop Jekyll are Octopress and Jekyll-Bootstrap. Both attempt to provide a simple blogging experience out of the box. Much of the Jekyll configuration done for you. Each of these projects has its own set of themes, making customization a snap.
To someone technical enough to want a static blog, but who is still looking to hit the ground running. I would point them to Jekyll-bootstrap or Octopress along with Pelican. Jekyll has a the largest community and the benefits that come with that.
Plugins
Jekyll has a ton of plugins. One that made Jekyll a contender for me is jekyll-rst. This allows you to write your posts in rst instead of markdown. The plugin is a bit rough around the edges and still requires you to install some python packages.
jekyl-s3 will deploy it to S3 for you which is nice if you you'd rather not mess with s3cmd.
Issues
I found a number of things about Jekyll confusing. Its docs are decent if a bit scattered.
It uses Liquid templating language, which was inspired by Django's templating language. Jinja2, also inspired by Django seems to me to be a much more mature implementation.
In general, Jekyll was not simple or inviting enough for a tool of its popularity. I think this helps to explain the demand for "frameworks" like Octopress on top of jekyll.
Hyde
Hyde started as a python port of Jekyll but has become something quite distinct. At first glance, Hyde seemed like the python option with the largest community. Since I still generally prefer Python to Ruby, Hyde was the first option I considered when building a static site last year.
The major problem with Hyde is that it has been between major versions for a long time. Hyde 1.0 remains mostly undocumented. The new version makes some welcome improvements like breaking its dependency on Django and moving to Jinja2 for templating. But, as a new user, I had no idea where to start on a Hyde project.
Cyrax
Cyrax was the next option I considered. It's also written in Python and uses Jinja2 templates. The author writes in the readme:
It's inspired from Jekyll and Hyde site generators and started when I realized that I'm dissatisfied with both of them by different reasons.
I found Cyrax to be generally well done. In general, it's better suited to websites than blogs; but it can do either. It allows you to use different layouts for different page types. This is very helpful in cases where you need more than just generic pages and blog posts.
The largest problems with Cyrax are its documentation and community. Any would-be contributors to Cyrax have hopefully found their way to Pelican.
Cyrax has some rough spots. For instance, the development server does not have a delay between refreshes. Rapidly editing lots of files can practically crash your machine if your site has more than a few pages.
New Ideas
NIH syndrome in this space aside, some exciting new projects are appearing.
Punch
Punch is a static website generator written in Javascript. All metadata is stored as JSON except long-form writing which can be done in markdown. The coolest part of punch is the ability to render pages on both the server and the client using the same code.
While I like the idea a lot, the project is just getting off the ground. Also, I'm not sure this hits a sweet spot for any particular usecase.
Someone who wants to serve pre-rendered content may not be happy having to input all of all their metadata with JSON. YAML is a better choice here if the users are supposed to hand-editing these files.
On the other hand, someone who wants a fully client-side site will likely choose a more full-featured build tool like Brunch. Brunch provides a framework that helps structure your code instead of your blog content. Or, if a user is more minimalistic, he will manage the Javascript and templates himself.
ruhoh
ruhoh is the new project from plusjade, the creator or jekyll bootstrap. What's exciting about this project is that, instead of allowing pluggable templating languages, its allows for a plugable implementation language. While the ruhoh API has to date only been implemented in Ruby , the plan is to build implementations for many popular languages.
The key insight here is that the choice of templating language should not be very important. If ruhoh can definite its entire API in any language, why not take care of any preprocessing in your programming language of choice? Mustache can handle rendering the content and still maintain a clear separation of concerns. Mustache is a good choice for this usecase because it already has bindings in most languages.
True language independence sounds like a great goal. If we view the function of static site generator as a simple transformation of data and allow the proper hooks for extensibility, ruhoh can provide something much more powerful than plugins for a single platform. Instead, it could allow for fullly customizable experience.
Variations on a build tool
Since all dynamic elements in a statically generated site will require Javascript, users of static generators might appreciate javascript-specific features like combining scripts and minifying them. These features exist in Javascript build tools like Sprockets or Brunch and tool that adds these features to a static site builder may be exactly what is needed to build sites that are rich in both content and client-side functionality.
A complete build tool might seem like overkill when a make/fab/rake/cake file combined wuth something like guard to watch your files and rebuild during the development is all that's required. While this will certainly work, it's a nontrivial problem since rebuilding everything from scratch after every change is not feasible for sites with lots of content or scripts.
In my opinion, we are still waiting for a build tool for modern, content-rich sites.