概要

とあるガイドを作ることになり、静的ページで1~3つくらいだろうということで静的ページジェネレーターのJekyllを使うことにしました。

Jekyll - Simple, blog-aware, static sites
http://jekyllrb.com/

今回は、Jekyllを生で使うのではなく、Gruntでコンパイルやリロード、js/cssのインライン展開、gzip圧縮などを自動化したかったので、Jekyll + Grunt + Yeoman構成でやってみました。

私は以下の3つの理由からJekyllを選択しました。

HTMLより手間の少ないし、慣れてるMarkdownでコンテンツを編集できるし、HTML生成が簡単であること
GitHub Pagesでページ公開すると際によく使われていること
Jekyllという名前の響きがいい感じだったこと

ちなみにBootstrapのGitHubリポジトリを見ると分かりますが、Bootstrapのページを作るためにもJekyll + Gruntが使われています。

はじめ方

まず、今回のやり方だと下記のものたちが必要になりますので、順次インストールしていきます。

Ruby 1.9+
Bundler
Yeoman
node.js
Grunt
generator-jekyllrb

環境作り

Rubyのインストール
参照先：
・インストールガイド - http://www.ruby-lang.org/ja/downloads/
・ rbenvを利用して複数バージョンのRubyをインストール - http://qiita.com/checkpoint/items/f8e65380d9cb0182218d
Bundlerのインストール
$ gem install bundler
Gruntのインストール
$ npm install -g grunt-cli
Yeomanのインストール
$ npm install -g yo
YeomanのJekyllジェネレーターをインストールする
$ npm install -g generator-jekyllrb

書き方

まずはJekyllでサイトの初期ファイルの生成をします。
$ mkdir site && cd site
$ yo jekyllrb

質問に答えていくと最終的に、下記のようなディレクトリ/ファイルが生成されます。

|-- Gemfile
|-- Gemfile.lock
|-- Gruntfile.js
|-- _config.build.yml
|-- _config.yml
|-- app
|   |-- _bower_components
|   |-- _includes
|   |-- _layouts
|   |   |-- default.html
|   |   `-- post.html
|   |-- _plugins
|   |-- _posts
|   |   |-- 2013-08-24-welcome-to-jekyll.md
|   |   `-- 2013-08-24-yo-jekyllrb.md
|   |-- _scss
|   |   |-- main.scss
|   |   |-- readme.md
|   |   `-- syntax.scss
|   |-- _src
|   |   `-- readme.md
|   |-- css
|   |-- fonts
|   |-- img
|   |-- index.html
|   `-- js
|       `-- main.js
|-- bower.json
|-- node_modules
|   |-- autoprefixer
|   |-- connect-livereload
|   |-- grunt
|   |-- grunt-autoprefixer
|   |-- grunt-concurrent
|   |-- grunt-contrib-clean
|   |-- grunt-contrib-coffee
|   |-- grunt-contrib-concat
|   |-- grunt-contrib-connect
|   |-- grunt-contrib-copy
|   |-- grunt-contrib-csslint
|   |-- grunt-contrib-cssmin
|   |-- grunt-contrib-htmlmin
|   |-- grunt-contrib-imagemin
|   |-- grunt-contrib-jshint
|   |-- grunt-contrib-sass
|   |-- grunt-contrib-uglify
|   |-- grunt-contrib-watch
|   |-- grunt-csscss
|   |-- grunt-jekyll
|   |-- grunt-open
|   |-- grunt-rev
|   |-- grunt-svgmin
|   |-- grunt-usemin
|   `-- matchdep
`— package.json

今回はMarkdownで編集したいので、index.htmlをindex.mdにリネームしてMarkdown記法で編集します。

MarkdownファイルやHTMLファイル、CSSを編集する前には下記コマンドでwatchタスクやlivereloadタスクを実行しておきます。
$ grunt server

さらに、Google Analyticsのコードを追加したり、ヘッダーやフッターを作ったりして、app配下はこんな感じにしてます。

|-- app
|   |-- _includes
|   |   |-- footer.html
|   |   |-- googleanalytics.html
|   |   |-- header.html
|   |   `-- scripts.html
|   |-- _layouts
|   |   `-- default.html
|   |-- _scss
|   |   `-- main.scss
|   |-- _src
|   |   `-- main.coffee
|   `— index.md

編集が完了したら、最終的成果物の作成を下記コマンドで行います。
$ grunt

defaultタスクとして、reportとbuildが割り当てられているため、HTMLファイルの生成前に、CSSのコーディングチェックも行われます。
HTMLファイルは、distディレクトリ配下に生成されるので、それを公開することになります。

トラブルシューティング

[問題] npm install -g ***を実行するとpermission deniedのようなメッセージが表示されて、インストールに失敗する。

[対応] npm installで-gオプションを指定すると、USER_HOMEの外のディレクトリにファイルを配置しようとするので、そこへの書き込み権限がないことが原因です。
対応案A. sudo npm install ***のようにsudoで実行する。
対応案B. rbenvやnvmを使ってRubyやNodeをインストールし、USER_HOME配下に置かれるようにする。

[問題] yo jekyllrbを実行するとTypeError: Cannot read property 'bold' of undefinedのようなメッセージが表示されて、インストールに失敗する。

TypeError: Cannot read property 'bold' of undefined
    at Object.<anonymous> (/Users/shoito/.nvm/v0.10.10/lib/node_modules/generator-jekyllrb/node_modules/yeoman-generator/lib/util/common.js:5:56)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Module.require (module.js:364:17)
    at require (module.js:380:17)
    at Object.<anonymous> (/Users/shoito/.nvm/v0.10.10/lib/node_modules/generator-jekyllrb/node_modules/yeoman-generator/lib/base.js:91:26)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)

[対応] yoのバージョン1.0.0〜1.0.3までだとこのエラーが発生するようです。エラーの発生する前のバージョンに下記のような手段で戻せます。
npm cache clean && npm uninstall -g yo && npm install -g yo@1.0.0-rc.1.4

いじょ。