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.
<pre class="wp-block-code">```
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
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 ``` ``` Downloading latest stable version of Node.js using NVM. `````` nvm install stable ``` ``` Setting the stable release as the default version. `````` 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 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](http://127.0.0.1:9000) 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 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 ``` ``` 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 `.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](http://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 ``` ``` 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 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.