Harp: A Static Site Generator Review

I have recently done a series of blog posts on the Harp static site generator. I would like to finish off this series by doing a review of Harp. I'll give you the pros, cons and then the use cases of this static site generator.


Harp is opinionated with regards to what technologies you want to use. The set is strictly limited to Jade, Markdown, and EJS for your server side html rendering; Sass, Less, and Stylus for CSS preprocessing; and CoffeeScript as a compile-to-JavaScript option. Of course you can also use plain old HTML, CSS, and JavaScript. This is good if a set of these technologies fit into your desired tech stack as there is no configuration necessary - these just work out of the box. They are also all easy to learn and so should not be a barrier to developers who do not have experience with them.

Additionally Harp has inherently structured metadata that is directly associated to the structure of the content of your webpages. This provides the ability to create contextually dependent features. It also uses JSON to store this metadata which is of course the right format to use for web development.

Lastly Harp has flexible support for integration and deployment. Changing the functionality or content is as easy as editing JSON files and rebuilding the site which makes it easy to integrate into larger systems. In addition the build command is simple and flexible making it easy to deploy however you want.


The metadata is not accessible via an API. If it were this could open up many opportunities for creating dynamic client side functionality.

The metadata associated with a page may exist in one of two places. It could exist as the top level properties of the _data.json file that lives as a sibling to it. Or it could exist one level up in the parent _data.json file under a property of the child directory name. This does not cause major issues as long as you are consistent but it is an opportunity for ambiguity.

The HTML templating options are limited. EJS is an old technology and many other JavaScript and Node based html templating options exist. The ones that come to mind are Mustache, Handlebars, and Dust. Having one of these or a similar html templating system available as apposed to EJS would be a huge improvement. This limitation also means that adding business logic to the templates becomes inevitable as the complexity of the application grows.

Lastly there is no built in support for metadata and layout inheritance. If the properties of the _data.json file could be inherited in child directories without having to add that logic into the HTML templates you could create rich features at a much lower complexity cost. Additionally having the _layout.ejs files inherit down the hierarchy so that a single layout could be defined and then all sub directories inherit that layout would again simplify your templates and make the code more dry.

Use Cases and Final Thoughts

I believe that Harp should be used for sites that focus on content over functionality where the build time business logic is minimal. In order to maintain data integrity you have to implement complex template logic that begins to reach outside of Harp's best use cases.

Popular Posts