Harp.js和GitHub Pages的文件夹结构有哪些最佳实践？

Question

我正在使用Harp创建一个静态网站，该网站将托管在GitHub页面上。到目前为止，一切都正常，但我有点担心文件夹结构。

这是因为GitHub页面期望要交付的文件位于存储库的根文件夹中。

所以我最终得到了当前的结构：

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

我困扰的是无法将README.md文件置于顶层目录（这意味着在GitHub上访问该存储库时，我总是被告知应该创建一个，并且需要手动下降一个级别），如果我不希望README.md通过GitHub页面公开。此外，构建步骤感觉很奇怪。在_sources文件夹中，我需要运行：

$ harp compile --output ..

这种在编译后将结果放在父文件夹中的方法感觉有些不对。虽然这是一个理论问题，但如果public文件夹中有一个_sources文件夹，那么我最终会得到一个大混乱的代码库 :-/。有没有一种方法可以使我把所有东西都放在顶层的_sources文件夹中，同时仍然能够像现在一样从GitHub页面上提供所有内容？

- Golo Roden

---

这里有一篇关于“发布到生产环境”的写作，链接为https://github.com/openoakland/openbudgetoakland/tree/master。 - Connor Leech

Answer 1

我发现使用了出色的 gh-pages npm 模块可以解决这个问题。以下是我的设置：

相关目录/文件：

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

相关的 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"
},

bin/publish的内容（这是coffeescript，但你可以轻松将其转换为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

为了发布，我只需要运行：

npm run publish

它将创建一个名为gh-pages的分支，并以dist目录的内容作为repo的根目录，并将其推送到github！更详细地说，在gh-pages文档中：

调用此函数将创建当前存储库的临时克隆，如果不存在，则创建gh-pages分支，从基本路径复制所有文件（或仅复制与可选src配置匹配的文件），提交所有更改并推送到origin远程。

对我而言，这个方法非常好用。希望能帮助其他人！

有一个完整的工作示例，这里是一个实时示例repo，使用上述所有配置（以及更多）。

- Harlan T Wood

Answer 2

很遗憾，你无法绕过Github pages需要根目录中的静态文件，以及Harp在编译时清除目标目录的事实。这可能感觉违反直觉，但仍然是一种推荐的工作流程，即将根目录文件存储在_sources等目录中，将编译后的文件存储在根目录中。此外，虽然harp compile会清空目标目录，但如果您不在该分支上进行编译，则仍然可以保留像README之类的文件在根目录中。您可以保持您的master分支干净，并只在gh-pages中进行编译以进行“部署”。

请查看我们当前的处理流程：https://github.com/openoakland/openbudgetoakland/tree/master。我仍然希望找到一种更好的方法来完成这项工作，但目前这就是可行的办法。

- jwfrench

---

感谢您的帮助 :-)) - Golo Roden

这基本上是正确的，尽管当您编译回一个目录时，harp不会清除您的源。这是处理该逻辑的源代码 https://github.com/sintaxi/harp/blob/master/lib/helpers.js#L237-L266 - sintaxi

Answer 3

让我总结一下使用Harp在Github Pages上部署用户/组织页面的工作流程，并希望能帮助到某些人。

编译前我的项目。

• _deploy 是一个简单的 Shell 脚本，负责编译、移动 README 并推送到 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

编译后。

请参见 this gist 以获取更多信息。

- Jorge Bucaran