jekyllは静的サイトジェネレータ。Github Pageなどでも使われており、ブログとしても使うことができて、ブログのフレームワークとしてOctopressやJekyll-Bootstrapがメジャーどころ。
OctopressやJekyll-Bootstrapを読んで勉強するのもありだがあえて素のjekyllを使って流れを理解するの巻。事前セットアップとしてRubyとbundlerは入れておいてください。
Step1
まずはブログとは関係ない任意のページをmarkdownで作成して公開する。
ファイル構成
.bundle/
└─ config
_layouts/
└─ default.html # レイアウト
_site/
│ code.html
│ index.html
└─ pygments.css
vendor/
└─ bundle/
.gitignore
_config.yml # jekyll構成ファイル
code.md # _site/code.htmlのソース
Gemfile
Gemfile.lock
index.md # _site/index.htmlのソース
pygments.css
Jekyllのインストール
作業ディレクトリを作ってGemfileを作成する。markdownの変換はredcarpetを使う。
source 'http://rubygems.org'
gem 'jekyll'
gem 'redcarpet'
bundle install --path vendor/bundle
構成ファイルの作成
まずは必要最低限。設定項目についてはConfigurationを参照。
markdown: redcarpet
exclude: ["vendor", "Gemfile", "Gemfile.lock"]
レイアウトファイルの用意
_layouts/default.htmlを作成する。_layoutディレクトリに拡張子htmlのファイルを置くとそれをページ側から参照できるようになる。ページ側から入力するコンテンツとしてpage.title, contentを入力している。テンプレートの詳細は Liquid を参照。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="utf-8">
<title>{{ page.title }}</title>
</head>
<body>
{{ content }}
</body>
</html>
最初のページを作る
トップディレクトリにindex.mdを作成する。
まずコンテンツの前に---で囲った内容をページの属性として設定できる。レイアウトで指定した名前が先ほどの_layout/名前.htmlで参照できる。titleに設定したものが先のレイアウトでは{{ page.title }}の部分になる。
---
layout: default
title: Hello
---
## 最初ページべし。
...ぜ。
サイトの確認
jekyll --serverコマンドでローカルにWebサーバを起動することができる。
bundle exec jekyll --server 3000 --auto
http://localhost:3000/でindex.mdの内容が表示されたらok。
コードハイライトを使う
Pygmentsを入れる。
OS Xの場合。
brew install python
export PATH="/usr/local/share/python:${PATH}"
easy_install pip
pip install --upgrade distribute
pip install pygments
構成ファイルを修正。1行目を追加。
pygments: true
markdown: redcarpet
exclude: ["vendor", "Gemfile", "Gemfile.lock"]
css作成
pygmentize -S default -f html > pygments.css
レイアウトファイルに追加。
<link rel="stylesheet" href="/pygments.css">
ページを作成、code.mdで保存。
---
layout: default
title: code
---
```ruby
p 'hello'
```
jekyll立ち上げ直し。さすがに_config.ymlの変更までは追従されない。
bundle exec jekyll --server 3000 --auto
http://localhost:3000/code.html が表示されたらok。
変数を使う
テンプレートで変数を使うことができる。いくつかの変数がビルトインで用意されておりTemplate-Dataで確認できる。
さらに_config.ymlに入れた値はviewではsite変数から参照できる。例えば以下のようにリソースのURLを設定しておき、テンプレートで参照することができる。
bootstrap_url: //netdna.bootstrapcdn.com/twitter-bootstrap/2.3.1
<link href="{{ site.bootstrap_url }}/css/bootstrap-combined.min.css" rel="stylesheet">
Step2
ブログのエントリーの作成
ブログのエントリーは_postディレクトリにYEAR-MONTH-DAY-title.MARKUPといった日付を含めたファイル名でページを作成する。
以下のような_post/2013-01-01-new-year.htmlを作成してまたjekyll --serverを起動する。
---
layout: default
title: 2013
---
<p>Happy, New Year!</p>
すると_site/2013/01/01/new-year.htmlというファイルが作成された。したがって http://localhost:3000/2013/01/01/new-year.htmlにアクセスができる。
_postにあるファイルをどういう階層で出力するかをpermalinkの設定で行える。指定できる項目は Permalinks を参照。作成されたファイルから逆算するとデフォルトの設定が
permalink: /:year/:month/:day/:title.html
になっていると理解できる。titleにマルチバイト文字を入れるとややこしくなるのでなるべく避ける方がいい。
エントリーを列挙する
_config.ymlにpaginateを設定する。
paginate: 3 # the number of post per page
paginateがindex.htmlでないと動作しないためトップディレクトリに以下のようなindex.htmlファイルを作成する。前回作ったindex.mdはhello.mdなどに変更しておく。
---
layout: default
title: Blog
---
{% for post in paginator.posts %}
<!-- here add you post markup -->
<h1><a href="{{ post.url }}">{{ post.title }}</a></h1>
<p class="author">
<span class="date">{{post.date}}</span>
</p>
<div class="content">
{{ post.content }}
</div>
{% endfor %}
<!-- Pagination links -->
<div class="pagination">
{% if paginator.previous_page %}
<a href="/page{{paginator.previous_page}}" class="previous">Previous</a>
{% else %}
<span class="previous">Previous</span>
{% endif %}
<span class="page_number ">Page: {{paginator.page}} of {{paginator.total_pages}}</span>
{% if paginator.next_page %}
<a href="/page{{paginator.next_page}}" class="next ">Next</a>
{% else %}
<span class="next ">Next</span>
{% endif %}
</div>
_config.ymlを変更したのでまたロールサーバを起動しなおすと、http://localhost:3000/ にアクセスすると投稿が一覧で表示される。
Step3
サーバに配置
Deploymentはいろいろ応用があって自動化もできる。
静的ファイルとして_siteに階層ができてあがっているので単純にこれをサーバのドキュメントルートにFTPでアップロードすることもできる。
サイトのコミット
静的ファイルと依存gemを除外する。
/_site
/vendor
終わりに
レイアウト使えてGithub Flavored Markdownで文章が書ける。エンジニアが会社やサービスのちょっとしたサイトを作らないといけないときはこれで十分な気がする。逆に非エンジニアの人が使うシステムに持っていくには編集やファイルの生成や配置の流れを考えると敷居が高い。
OctopressやJekyll-Bootstrapを使うとブログに必要なページをより簡単に作成することができる。