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を使う。

Gemfile

source 'http://rubygems.org'

gem 'jekyll'
gem 'redcarpet'

bundle install --path vendor/bundle

構成ファイルの作成

まずは必要最低限。設定項目についてはConfigurationを参照。

_config.yml

markdown: redcarpet
exclude: ["vendor", "Gemfile", "Gemfile.lock"]

レイアウトファイルの用意

_layouts/default.htmlを作成する。_layoutディレクトリに拡張子htmlのファイルを置くとそれをページ側から参照できるようになる。ページ側から入力するコンテンツとしてpage.title, contentを入力している。テンプレートの詳細は Liquid を参照。

_layouts/default.html

<!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 }}の部分になる。

index.md

---
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行目を追加。

_config.yml

pygments: true
markdown: redcarpet
exclude: ["vendor", "Gemfile", "Gemfile.lock"]

css作成

pygmentize -S default -f html > pygments.css

レイアウトファイルに追加。

_layouts/default.html

<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を設定しておき、テンプレートで参照することができる。

_config.yml

bootstrap_url: //netdna.bootstrapcdn.com/twitter-bootstrap/2.3.1

_layouts/default.html

<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を起動する。

_post/2013-01-01-new-year.html

---
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などに変更しておく。

index.html

---
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を除外する。

.gitignore

/_site
/vendor

終わりに

レイアウト使えてGithub Flavored Markdownで文章が書ける。エンジニアが会社やサービスのちょっとしたサイトを作らないといけないときはこれで十分な気がする。逆に非エンジニアの人が使うシステムに持っていくには編集やファイルの生成や配置の流れを考えると敷居が高い。

OctopressやJekyll-Bootstrapを使うとブログに必要なページをより簡単に作成することができる。

JekyllをStep by Stepで使って理解する

Step1

ファイル構成

Jekyllのインストール

構成ファイルの作成

レイアウトファイルの用意

最初のページを作る

サイトの確認

コードハイライトを使う

変数を使う

Step2

ブログのエントリーの作成

エントリーを列挙する

Step3

サーバに配置

サイトのコミット

終わりに