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:
/
.gitignore
index.html
_sources/
harp.json
README.md
public/
index.ejs
What worries me is that I cannot have the file README.md
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 README.md 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
I found a great solution for this with the fantastic gh-pages npm module. Here's my setup:
Relevant files / files:
README.md
bin/
publish
dist/
node_modules/
package.json
src/
_layout.jade
index.md
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
docs:
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 optionalsrc
, copy all changes and push to the remoteorigin
.
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).
source to share
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 https://github.com/openoakland/openbudgetoakland/tree/master . I'd still like to find a less hacky way to do it myself, but it works now.
source to share
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.
-
_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
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 compilation.
See this method for details .
source to share