概要
とあるガイドを作ることになり、静的ページで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
いじょ。