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


[jekyll](http://jekyllrb.com/)は静的サイトジェネレータ。Github Pageなどでも使われており、ブログとしても使うことができて、ブログのフレームワークとして[Octopress](http://octopress.org/)や[Jekyll-Bootstrap](http://jekyllbootstrap.com/)がメジャーどころ。

OctopressやJekyll-Bootstrapを読んで勉強するのもありだがあえて素の[jekyll](http://jekyllrb.com/)を使って流れを理解するの巻。**事前セットアップとして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を使う。 

```ruby:Gemfile
source 'http://rubygems.org'

gem 'jekyll'
gem 'redcarpet'
```

```
bundle install --path vendor/bundle
```

## 構成ファイルの作成

まずは必要最低限。設定項目については[Configuration](https://github.com/mojombo/jekyll/wiki/configuration)を参照。

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

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

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

```html:_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/](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
```

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

```html:_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](http://localhost:3000/code.html) が表示されたらok。

## 変数を使う

テンプレートで変数を使うことができる。いくつかの変数がビルトインで用意されており[Template-Data](https://github.com/mojombo/jekyll/wiki/Template-Data)で確認できる。

さらに_config.ymlに入れた値はviewでは**site**変数から参照できる。例えば以下のようにリソースのURLを設定しておき、テンプレートで参照することができる。

```:_config.yml
bootstrap_url: //netdna.bootstrapcdn.com/twitter-bootstrap/2.3.1
```

```html:_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](http://localhost:3000/2013/01/01/new-year.html)にアクセスができる。

_postにあるファイルをどういう階層で出力するかをpermalinkの設定で行える。指定できる項目は [Permalinks](https://github.com/mojombo/jekyll/wiki/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/](http://localhost:3000/) にアクセスすると投稿が一覧で表示される。

# Step3

## サーバに配置

[Deployment](https://github.com/mojombo/jekyll/wiki/Deployment)はいろいろ応用があって自動化もできる。

静的ファイルとして``_site``に階層ができてあがっているので単純にこれをサーバのドキュメントルートにFTPでアップロードすることもできる。

## サイトのコミット

静的ファイルと依存gemを除外する。

```:.gitignore
/_site
/vendor
```

## 終わりに

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

[Octopress](http://octopress.org/)や[Jekyll-Bootstrap](http://jekyllbootstrap.com/)を使うとブログに必要なページをより簡単に作成することができる。