Create a blog in Harp

by

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](https://raw.githubusercontent.com/creationix/nvm/v0.25.4/install.sh) | bash
Code language: JavaScript (javascript)

or

wget -qO- [https://raw.githubusercontent.com/creationix/nvm/v0.25.4/install.sh](https://raw.githubusercontent.com/creationix/nvm/v0.25.4/install.sh) | bash
Code language: JavaScript (javascript)

Downloading latest stable version of Node.js using NVM.

nvm install stable

Setting the stable release as the default version.

nvm alias default stable
Code language: JavaScript (javascript)

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 initialize 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
Code language: CSS (css)

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 must 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 several types of global variables. Let’s delete the files in the Website folder first. Now let’s start by creating the harp.json file. Now open the harp.json file.

touch harp.json
Code language: CSS (css)

Add the following lines to the harp.json file.

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

}Code language: JSON / JSON with Comments (json)

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
Code language: PHP (php)

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
Code language: CSS (css)

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 .html.

touch index.jade
Code language: CSS (css)

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 itself, you need to feed this data manually using a _data.json file. Add the _data.json file.

touch _data.json
Code language: CSS (css)

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" 
	} 
}
Code language: JSON / JSON with Comments (json)

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}
Code language: PHP (php)

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.Code language: JavaScript (javascript)

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
Code language: PHP (php)

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