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

Question

I'm using Harp to create a static website that shall be hosted on GitHub pages. So far, everything works, but I'm a little bit concerned about the folder structure.

This is because GitHub pages expects the files that shall be delivered in the root folder of the repository.

So I ended up with the current structure:

/
  .gitignore
  index.html
  _sources/
    harp.json
    README.md
    public/
      index.ejs

What bothers me is that I can not have the README.md file on top-level (which means that when going to the repository on GitHub, I am always told that I should create one, and that I need to step down one level manually), if I do not want the README.md to be public via GitHub pages as well.

Additionally, the build step feels strange. From within the _sources folder I need to run:

$ harp compile --output ..

This somehow feels wrong, compiling something and putting the result in the parent folder. It's a theoretical question, but if there was a _sources folder within the public folder, I'd end up with a big ball of mud :-/

Is there any way of how to structure this so that I can have everything in the _sources folder on top-level, while still being able to serve everything as it now is from GitHub pages?

there's a writeup here under 'publishing to production' https://github.com/openoakland/openbudgetoakland/tree/master — Connor Leech, Oct 30 '14 at 22:03

Harlan T Wood · Accepted Answer · 2015-04-22T09:03:34.603

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

Relevant dirs/files:

README.md
bin/
    publish
dist/
node_modules/
package.json
src/
    _layout.jade
    index.md

Relevant lines of 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"
},

Contents of 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 publish, I simply run:

npm run publish

and it creates the gh-pages branch with the contents of the dist dir as the root of the repo, and pushes it to github!

In more detail, from the gh-pages docs:

Calling this function will create a temporary clone of the current repository, create a gh-pages branch if one doesn't already exist, copy over all files from the base path, or only those that match patterns from the optional src configuration, commit all changes, and push to the origin remote.

This works like a charm for me. Hope it helps others!

For a full working example, here is a live example repo using all of the configuration described above (and more).

score 3 · Answer 2 · answered Oct 31 '14 at 18:06

Unfortunately, there's not much you can do to get around the fact that Github pages requires static files in the root directory, and the fact that Harp clears the target directory on compile. It may feel counterintuitive, but storing your root files in a directory like _sources with the compiled files in root is still the prescribed method for this workflow. Additionally, while harp compile clears out the target directory, you can still keep files like your README in the root if you don't compile on that branch. You can keep your master branch clean and then only compile in gh-pages to 'deploy'.

Check out our current process at https://github.com/openoakland/openbudgetoakland/tree/master. I'd still like to find a less 'hacky' way to accomplish this myself, but this is what works for now.

This is mostly correct though harp does not clear out your source when you compile back one dir. Here is the source that handles that logic https://github.com/sintaxi/harp/blob/master/lib/helpers.js#L237-L266 — sintaxi, Nov 25 '14 at 13:33

Jorge Bucaran · Answer 3 · 2014-11-10T16:34:24.880

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

My project before compiling.

Directory before compiling.

_deploy is a simple shell 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
fi

# 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 _README.md ../
cd ..
mv _README.md README.md

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

After compiling.

Directory after compiling

See this gist for more.

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

3 Answers3