Are there any guidelines for folder structure with Harp.js and GitHub pages?

I am using Harp to create a static website that is hosted on GitHub pages. Everything works so far, but I'm a little concerned about the folder structure.

This is because GitHub pages expect files to be delivered to the root of the repository.

So I ended up with the current structure:



What worries me is that I cannot have the file

at the top level (which means that when I go to a repository on GitHub I am always told that I have to create it and that I need to retire one level manually) unless I want to so that is publicly available through the GitHub pages.

Also, the build step seems strange. From inside the folder, _sources

I need to run:

$ harp compile --output ..


This is somehow wrong, compiles something and puts the result in the parent folder. This is a theoretical question, but if there public

was a folder in the folder _sources

, I would have a big ball of dirt: - /

Is there a way to structure this so that I can have everything in a folder _sources

at the top level while still being able to serve everything as it is now from the GitHub pages?


source to share

3 answers

I found a great solution for this with the fantastic gh-pages npm module. Here's my setup:

Relevant files / files:


Relevant lines package.json


"scripts": {
  "compile": "harp compile src dist",
  "publish": "npm run compile && bin/publish"
"devDependencies": {
  "coffee-script": "^1.9.2",
  "gh-pages": "^0.2.0",
  "harp": "^0.13.0"


Content bin/publish

(this is coffeescript, but you can easily convert it to JS ):

#!/usr/bin/env coffee

ghpages = require 'gh-pages'
path = require 'path'

handle_error = (error) ->
  if error
    console.error error
    process.exit error.code or 1

dist = path.join __dirname, '..', 'dist'

ghpages.publish dist, handle_error


To post, I just run:

npm run publish

and creates a gh-pages branch with the content dist

dir as the root of the repo and pushes it to github!

In more detail, from the gh-pages


Calling this function will create a temporary clone of the current repository, create a branch gh-pages

if it doesn't already exist, copy all files from the base path or only those that match patterns from the optional src

, copy all changes and push to the remote origin


It works like a charm for me. Hope this helps others!

For a complete working example, here's a live repo example using all of the configuration above (and more).



Unfortunately, you cannot get around the fact that Github pages require static files in the root directory and the fact that Harp clears out the target directory on compile

. It might sound like a contradiction, but storing your root files in a directory like _sources with the compiled files at the root is still the prescribed method for this workflow. Also, while harp compile

clearing out the target directory, you can still store files like the README in the root if you don't compile on that branch. You can keep the branch master

clean and then only compile gh-pages

to "deploy".

Check out our current process at . I'd still like to find a less hacky way to do it myself, but it works now.



Let me summarize my workflow for deploying to User / Organization to Github Pages using Harp and hopefully help someone out there.

My project before compilation.

Directory before compiling.

  • _deploy

    is a simple wrapper script to take care of compiling, moving the README and pushing to Github.
# change dirs to _src if not already in there
if [ ${PWD##*/} != "_src" ]; then
  cd _src

# source is the current directory and the target the parent directory
harp compile ./ ../

# files starting with _ are not copied to target. copy _README and rename
cp ../
cd ..

# commit to the repo and push to github 
git add .
git commit -m "Deploy."
git push


After compilation.

Directory after compiling

See this method for details .



All Articles