Create a blog in Harp

Harp is a free, open source static site server written in Node.js, It support EJS and Jade for templating and Sass,Scss, Less and Stylus for stylesheets pre-processing and Markdown for writing pages.

What do I mean by static site server?

A static site allows you to use pre-processor for writing templates, scripts, stylesheets and pages, and output them into static content, at the same time serve those static content.

How different is a static site server from a static site generator?

A static site generator compiles the output once you are done writing them, and have to be deployed manually or through some automated script, some static site generators support deployment options like GitHub Pages, SSH and many other ways, but at the end these files have to be placed in some web root where a separate production server like NGINX or Apache have to serve them, and in most static site generators you have to compile the source manually, which might be a bit painful over a long term. How is Harp different? Harp is a static site server which means every time you make changes to a file it will recompile it, at the same time Harp has a built-in web server that can run in both development and production. In development Harp will recompile the whole source, while in production mode Harp keeps an eye on the timestamp of the files, So if a file has changes made to it, Harp will recompile it, but this time, not the whole source only that one specific file. So now you have a server that compiles and hosts your website. If you want to use Harp as a static site generator, you can do that.

Getting started

Since Harp is written in Node.js we need to get Node.js first. (If you have Node.js already installed skip this step). Visit nodejs Download the specific version of Node.js installer for your Windows, Mac or Linux. If you are using Windows you might need to reboot your PC so that the environment variables are set and NPM has the right permissions. If you prefer using NVM you can go ahead, and follow the steps below.

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.25.4/install.sh | bash  

or

wget -qO- https://raw.githubusercontent.com/creationix/nvm/v0.25.4/install.sh | bash  

Downloading latest stable version of Node.js using NVM.

nvm install stable  

Setting the stable release as the default version.

<code class="bash">nvm alias default stable  

Installing Harp

If you are using Windows or NVM then you don’t need to run sudo before running this command.

sudo npm install -g harp  

Once Harp is done installing we can initialise a new Harp project.

harp init Website  

Now set you current directory Website.

cd Website  

If you want to create a Harp project in an existing folder, run.

harp init .  

Running the Harp server.

harp server  

If you want to compile the output to host it, or prefer a different Web Server. You can compile the output by using. The output should be stored in a folder named www

harp compile  

Now visit here You source folder structure inside Website should look like.

404.jade  
_layout.jade  
index.jade  
main.less  

Any file an underscore before the name will not be visible to the public for example a _data.json file. Harp does not have a logical module, so you really can’t use a for loop to list the child pages of a specific folder. You have to use a _data.json file that stores all the data you require.

Creating a blog.

To create a blog we need a completely new folder structure. The folder will contain all the files we require to create a basic blog.

.blog/
 ..hello-harp.md
 .._layout.jade
 .._data.json
._layout.jade
.index.jade
harp.json  

The harp.json file holds all the global variables like metadata website title and many different types of global variables. Lets delete the files in the Website folder first. Now lets start by creating the harp.json file. Now open the harp.json file.

touch harp.json  

Add the following lines to the harp.json file.

{  
  "globals": {
    "site": {
      "title": "Harp Blog",
      "description": "A simple blog powered by Harp"
    }
  }
}

Now you have your globals set. Creating the public folder, anything stored in the public folder will be accessible to the visitor unless it has an _ before the name for example _data.json

mkdir public  

We will be using Jade for templating. If you wan’t to use EJS you can go ahead and use EJS. Now create a _layout.jade inside the public folder.

touch _layout.jade  

Add the following lines to the _layout.jade file.

doctype html  
html  
  head(lang="en")
    meta(charset="utf-8")
    meta(name="description" content="#{site.description}")
    title #{site.title}
  body
    .content
      != yield

You must have noticed that inside the _layout.jade in the .content div, inside that div we have a != yield What does that do? It wrappers the _layout.jade file will be the patent of all the other templates, What does that mean? It means that you really don’t need to write all the Jade markup over and over in every new file you create in the folder that contains a _layout.jade, It saves a lot and lets you have a constant markup for multiple pages. Now that we have a _layout.jade, lets add a new index.jade file. The index.jade file is the file that will output as index.html, actually all the files except the _layout.jade file will be output would be as <filename>.html.

touch index.jade  

Now add the following lines to the index.jade

h2 Hello Harp  
p Powered by Harp  

Now when you visit 127.0.0.1:9000, you should see the greeting that we just created. It time now to add the listing functionality to the index.jade file. As I said before, Harp will not list the pages all by it self, you need to feed this data manually using a _data.json file. Add the _data.json file.

touch _data.json  

Now we can add the pages data to the _data.json file you want to list.

{  
    "hello-harp": {
        "title": "Hello Harp",
        "description": "An example post"
    }
}

Now we can edit the index.jade file to fetch this information.

for post, slug in public.blog._data  
    h2: a(href="/blog/#{slug}") #{post.title}
    p #{post.description}

Now you should see the hyperlink based title and the new description. It’s time to create the hello-harp.md in our blog folder.

touch blog/hello-harp.md  

You can add this dummy text to the hello-harp.md file.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod  
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,  
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo  
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse  
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non  
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.  

You will now require a _layout.jade inside the blog folder, you can add the following lines to it.

doctype html  
html  
  head(lang="en")
    meta(charset="utf-8")
    meta(name="description" content="#{site.description}")
    title #{site.title}
  body
    .content
      h2 #{title}
      != yield

You now have a fully functional blog powered by Harp. This was a basic tutorial, I did not involve any stylesheets, because I believe you are creative enough to implement you own style of stylesheet, and wanted to give the read to choose the pre processor, he/she would want to use. If you like this tutorial, share or comment, if you have any questions.