Hosting Harp on Github Pages

Harp is a static site generator that I have recently been learning. As always I start even the smallest projects with hosting and deployment in mind. I looked at the best ways to host Harp and thought about Firebase and Heroku. However I realized that because Harp is a static site generator it might make sense to not use up one of three free tier slots on either Firebase or Heroku and instead use Github pages. In this blog post I will discuss hosting Harp on Github pages. If you have not already it might be beneficial to go back and read by previous blog post on Harp called Getting Started with Harp.

Step 1: Don't use the project initialization

Instead simply create the following project directory structure:
  • my-project/
    • src/
    • docs/
Add the following contents to the file:
## My Project Name

### Setup
npm install -g harp

### Development
harp server src

Go to localhost:9000

### Deployment
harp compile src docs
git add .
git commit -m "Recompiled."
git push origin master

Inside the src folder create an "index.ejs" file with the following contents:
<!DOCTYPE html>
    <h1>Hello, World!</h1>
Now run the following commands:
harp compile src docs
git init
git add .
git commit -m "Init commit."

Step 2: Create a Github Remote Repository

Go to and create your repository entering a name but do not select any of the other options. After doing so follow the "push an existing repository from the command line" instructions.

Step 3: Setup Github Pages

Go to the settings of the newly created github repository and scroll to the "Github pages" section. In the source dropdown you should have a "master branch /docs folder" option. Select this option and choose save. Your Harp static site should now be available at the the url provided by Github at the top of the "Github Pages" section of the settings page.

Step 4: Provide a Custom Domain

This is obviously optional and requires that you own a domain name. I am also assuming that you will be placing the website on a subdomain of the domain.

Go to your DNS manager and add a CNAME record with a "name" of the subdomain you want to use and a "value" of "<your github username>". Your website should now be available on your domain under the provided subdomain. For example I have a Harp website hosted on

And that is it! You should now be setup to develop a static website using Harp and see your changes live. Remember that we added the development and deployment steps in the readme of the project.


Popular Articles

The Vanilla Javascript Component Pattern

The Sunless Citadel: A D&D 5e Session Report

Getting Started with Harp