2015.03.22

Hugo Boilerplate

Hugoのドキュメンテーションはとても充実していて良いのだが、最小構成がそもそも小さいのでコードレベルで把握してしまったほうがわかりやすい可能性がある。

1000ch/hugo-boilerplateは、Hugoの主な機能を最小限の形にまとめたリポジトリ。

HugoのインストールとHugo Boilerplateの利用

HugoはHomebrewでインストール。既にインストールしてある場合はアップデートすること。

$ brew install hugo
$ brew update

インストールしたらリポジトリをクローンして、npm startするだけ。

$ git clone [email protected]:1000ch/hugo-boilerplate.git
$ cd hugo-boilerplate
$ npm start

npm startはhugo server --watchのエイリアスで、実行されるとlocalhost:1313で表示できる。--watchオプションでファイルを監視しているので、更新があるとリアルタイムにビルドが実行される。

ファイル構成

Hugo Boilerplateのファイル構成は以下のようになっている。Source Organizationに詳細がのっている。

content・layouts・staticフォルダ

contentとlayoutsはその名の通りコンテンツとそれをレイアウトするファイルを配置するフォルダ。

content配下にサンプルのMarkdownをいくつか置いてあるが、content/archives/sample-post.mdであれば [DocumentRoot]/archives/sample-post.html に変換される。

layoutsにはarchives・indexes・partialsフォルダがあるが、大枠を構成しているのはarchives/single.htmlというファイルで、先ほどのcontent/archives配下のMarkdownファイルはこちらをレイアウトとして利用する。また、_defaultフォルダに同じくsingle.htmlを作れば、明示的にレイアウトファイルを用意しない場合に参照される。

partialsフォルダには共通となるHTMLを切り出して、archives/single.htmlからインクルードしている。indexesフォルダにはarchives.htmlがあるが、これはcontent/archives配下のコンテンツを列挙する命名規則。

staticフォルダにはCSSやJSのような静的ファイルを配置する。

各種設定ファイル

.editorconfig
.gitignore
config.yml Hugoの設定ファイル。設定すべき項目はおおよそ指定してあるけど、さらなる詳細はConfiguring Hugo
readme.md リポジトリのREADME
wercker.yml Werckerの設定ファイル。

この辺は好みに応じて編集すべきファイル。.editorconfigがわからない人はEditorConfigで文字コード設定を共有して喧嘩しなくなる話 | Ginpen.comを見ると良い。

package.json
bower.json
gulpfile.js

Gulpで静的ファイルをビルドし、staticフォルダに配置するようにしている。Hugoの--watchもあるので、ターミナルの別タブでgulp watchをすると静的ファイル群の監視ができるので、プロジェクトのレイアウトやJSでの構築といった段階では必須になるかも。

Werckerによる自動デプロイ

Hugoの成果物（ビルド結果）は_publicフォルダに出力されるので、ホストサーバーにはそれを配置すれば良い。が、GitHub Pagesで運用している場合はWerckerを使った運用をオススメしたい。

Automated deployments with Werckerに完璧なドキュメントがあるので割愛するが、wercker.ymlは作ってあるのでWerckerからGitHubのリポジトリにアクセスするためにGitHubのトークンを作ってジョブに登録するだけ。

これで、masterブランチにpushするとビルド結果が_publicフォルダ配下がgh-pagesブランチにpushされる。