Building Sites with HarpJS

, by André Jaenisch . About 5 min reading time.

Last month, I participated at an internal hackathon.I picked the goal to pull data from our current solution for documentingstyles via ReST and render it as static site, while everything was trackedin git. Some other developers and a designer joined me in it and in the endwe even won a prize :-)

In order to not forget my learnings, I want to document them.I even redid my homepage in harp.js, to learn more of how it works.So let's go!

Installation

Convention over configuration

Harp.js works with conventions. It expects you to have a harp.json in theroot of a directory and a public directory with your content.

Every file or directory under public which starts with an underscore willnot be served.

Harp.js can handle layouts in jade (sic!) and ejs out-of-the-box.Since Jade was renamed in Pug due to trademark issues, I will go for ejs(embedded JavaScript) here.

On the CSS side you can simply pick one of several preprocessors and harp.jswill automatically compile it for you.If you don't like JavaScript, you can use CoffeeScript, too.Inside the public directory, you can create _data.json files which hold metadata of your files.

As you can see, the pageTitle would be rendered between <%- .. %>if present. Otherwise I am falling back to a globally defined title, which youcan define in harp.json.My WebMention are already somewhat working too, but I didn't grokked themenough to blog about it, yet.

You may have noticed, that in the file structure above, I am using .lessfiles, but here I am using references to plain .css. HarpJS does thetransformation for me. I will explain how to define the target extension later,when I am coming to the creation of a sitemap.xml.

Another interesting partial could be header.ejs, so let's look at its content:

<ahref="/">Home</a><nav>
<%- partial("header-navigation") %>
</nav>

As you can see, you can use partials inside partials! Moreover, inside thedirectory, you are referring to other files with their relative path.This makes it possible to group them in logical directories, which can bemoved around without the need to rename the references inside them.

harp.json and _data.json

Next, look at harp.json:

{"globals":{"uri":"https://jaenis.ch","title":"André Jaenisch"}}

Here we can define variables, which will become site-wide available.If you need locally variables, use _data.json like so:

Pay attention on the filename /public/sitemap.xml.ejs. Here I am advisingHarpJS to render this file and output it as sitemap.xml in the root directoryof my website. sitemap-website.xml.ejs is controlled by HarpJS, too.

What's going on here? Recursion! Read it from buttom to top.If you have questions, read it again. If there are still question marks inyour head, drop me a mail. I know, that not everybody understands recursivealgorithms easily :-)

Render it!

After we covered the interesting bits, let's render it!First a word of warning: HarpJS will wipe the target directory first!

This took me about half an hour after my first try. Luckily my hoster provideda backup on a daily basis (meaning, I lost "only" 20 hours worth ofanalytics...).

Embedding of opt out is not supported by your browser. Please visit https://jaenis.ch/piwik/index.php?module=CoreAdminHome&action=optOut&language=en&backgroundColor=ffffff&fontColor=000000&fontSize=1em&fontFamily=serif