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

admin管理员组

文章数量:1418303

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 pile --output ..

This somehow feels wrong, piling 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?

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 pile --output ..

This somehow feels wrong, piling 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?

• javascript
• node.js
• github
• github-pages
• harp

Share Improve this question Follow asked Oct 8, 2014 at 3:57 Golo RodenGolo Roden 151k102102 gold badges315315 silver badges444444 bronze badges 1

• 1 there's a writeup here under 'publishing to production' github./openoakland/openbudgetoakland/tree/master – Connor Leech Commented Oct 30, 2014 at 22:03

Add a ment  | 

3 Answers 3

Sorted by: Reset to default 5

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": {
  "pile": "harp pile src dist",
  "publish": "npm run pile && 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, mit 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).

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 pile. It may feel counterintuitive, but storing your root files in a directory like _sources with the piled files in root is still the prescribed method for this workflow. Additionally, while harp pile clears out the target directory, you can still keep files like your README in the root if you don't pile on that branch. You can keep your master branch clean and then only pile in gh-pages to 'deploy'.

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

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 piling.

• _deploy is a simple shell script to take care of piling, 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 pile ./ ../

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

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

After piling.

See this gist for more.

本文标签： javascriptAre there any best practices for folder structure with Harpjs and GitHub pagesStack Overflow