KOMIYA Atsushi

KOMIYA Atsushi

Software engineer in Tokyo.

Minimal Mistakes テーマではじめる Github Pages with Jekyll

ブログシステムとして Jekyll と Minimal Mistakes テーマを導入してみたメモです。

はじめに

ここ 6 年ほどは (年間の投稿量はわずかながら) Blogger を使ってブログエントリを書いてきましたが、

  • 標準では Markdown 入力に対応しておらず、タグを手打ちしなければならなくて辛い
  • ゴテゴテしておらずシンプルでいい感じのテーマが少ない
  • かといってテーマをカスタマイズしようとすると、それはそれでタグ地獄に陥って辛い
  • モバイル対応が十分とは思えない

などの理由により、この先も Blogger を継続して利用するのは難しいと判断し、ブログシステムを Github Pages with Jekyll に乗り換えることにしました。

なお、乗り換え先のブログサービス・ブログシステムとして、今回はてなブログと Hugo, Jekyll を比較検討しながらも、

  • はてなブログ: 機能的にほぼ満足だし面倒ごとが少なそうでよい選択肢だと思ったのだけど、他の方のブログとテーマ被りしそう
  • Hugo: Golang よりは Ruby が好き (いざとなれば、コードを読んで容易に理解できる)

という、わりとどうでもいい理由で、若干枯れた技術感のある Jekyll を選択したのでした。

テーマ選び

さて、ブログシステム (のうちの、静的サイトジェネレーター) として Jekyll を使うとしても、 フロントエンジニアでも何でもない、デザインセンスのないしがないサーバサイドエンジニアな人間が使うとなると、 Jekyll テーマを別途探してくる必要があります。

テーマを探すと言っても、単に “jekyll themes” のクエリで Google 検索すれば、それなりの数の Jekyll テーマ集なサイトがたくさん引っかかります。今回はその中から、いくつかのサイトをめぐって Minimal Mistakes というテーマを見つけ、こちらを使うことにしました。

環境構築 & テーマのインストール

この Jekyll の環境構築および Minimal Mistakes のインストールは、Ruby の環境が既に存在する前提で話を進めます。 環境構築の手順は、次のようにとてもシンプルです。

  1. Minimal Mistakes をインストールする
  2. Jekyll 含めた依存モジュール (gem) 一式をインストールする

Minimal Mistakes のインストールは、ドキュメントの Installation にあるとおり、 git リポジトリをチェックアウトするなり zip アーカイブをダウンロード & 展開するなりします。

続いて、Minimal Mistakes のファイル一式に含まれている Gemfile をテキストエディタで編集します。 Jekyll そのもののインストールも合わせて bundle install コマンドで片付けたいのであれば、 以下のように gem "jekyll" の部分をアンコメントします。

# If you want to use Jekyll native, uncomment the line below.
# To upgrade, run `bundle update`.

gem "jekyll"

加えて、タグやカテゴリのページを生成するための jekyll プラグインである jekyll-archives のインストールも合わせてできるように、 以下のように gem "jekyll-archives" もアンコメントします。

# If you have any plugins, put them here!
group :jekyll_plugins do
  gem "jekyll-archives"
end

最後に bundle install コマンドをキメれば、環境構築はお終いです。

bundle install --path vendor/bundler

設定

続いて、ひとまず HTML を生成するのに必要な設定をしていきます。

_config.yml の編集

まずは Minimal Mistakes のドキュメント Configuration を見ながら _config.yml を編集していきます。

サイトそのものに関わる設定は Site Settings にて記述します。

# Site Settings
locale                   : "ja-JP"  # 日本語を扱うなら変更しておく
title                    : "サイトのタイトル"
name                     : "サイト所有者の名前"
description              : "Open graph の description などに設定される内容をここに書く"
url                      : "https://your-github-name.github.io"  # スキーム (http/https) およびホスト名を指定する
repository               : "your-github-name/your-github-name.github.io"  # GitHub 上のリポジトリを指定する

サイト所有者 (ブログの著者) に関する情報は Site Author に記述します。

# Site Author
author:
  name             : "サイト所有者の名前"
  avatar           : "avatar_icon.png"  # 丸囲みの枠内に表示したい画像のファイル名を指定する (images/ 配下にファイルを置いておく)
  bio              : "ちょっとしたプロフィールをここに書く"

Jekyll の環境構築で bundle install --path vendor/bundler とした場合は、vendor/ ディレクトリ配下に gem がインストールされているはずです。 そのため、Reading Files にて、vendor/ ディレクトリ以下のファイルを Jekyll で処理しないように exclude 指定しておきます。

# Reading Files
include:
  - .htaccess
  - _pages
exclude:
  - vendor  # これを追記する
  # ...

タグおよびカテゴリの一覧ページを生成するために、 jekyll-archives のプラグインを有効にします。 まずは Plugins の gems リストにて、jekyll-archives を追記します。

# Plugins
gems:
  - jekyll-archives

また、Archives にて category_archive および tag_archive の type 属性を jekyll-archives に変更します。

# Archives
#  Type
#  - GitHub Pages compatible archive pages built with Liquid ~> type: liquid (default)
#  - Jekyll Archives plugin archive pages ~> type: jekyll-archives
#  Path (examples)
#  - Archive page should exist at path when using Liquid method or you can
#    expect broken links (especially with breadcrumbs enabled)
#  - <base_path>/tags/my-awesome-tag/index.html ~> path: /tags/
#  - <base_path/categories/my-awesome-category/index.html ~> path: /categories/
#  - <base_path/my-awesome-category/index.html ~> path: /
category_archive:
  type: jekyll-archives  # liquid から jekyll-archives に変更する
  path: /categories/
tag_archive:
  type: jekyll-archives  # liquid から jekyll-archives に変更する
  path: /tags/

合わせて、その Archives の直後にある jekyll-archives の設定をアンコメントしておきます。

# https://github.com/jekyll/jekyll-archives
jekyll-archives:
  enabled:
    - categories
    - tags
  layouts:
    category: archive-taxonomy
    tag: archive-taxonomy
  permalinks:
    category: /categories/:name/
    tag: /tags/:name/

_config.yml 編集の締めとして、Front Matter Defaults の既定値を設定しておきましょう。 これにより、SNS シェアボタンなどを一律に表示させることができるようになります。

defaults:
  # _posts
  - scope:
      path: ""
      type: posts
    values:
      layout: single
      author_profile: true
      read_time: true
      comments: true
      share: true
      related: true

ナビゲーション

次はページ上部に表示される masthead バー部分のリンクを編集します。ファイルは _data/navigation.yml です。 デフォルトでは Minimal Mistakes のドキュメントへのリンクが設定されていますが、普通は不要だと思うので削除してしまいます。 特にリンクしたいものがなければ、以下のように空にしておきます。

main:

表示確認

ひととおり設定ができたら、jekyll serve コマンドにてローカルで HTTP サーバを立ち上げ、ブラウザで http://127.0.0.1:4000/ にアクセスしてサイトの表示を確認します。

bundle exec jekyll serve

…おおっと、CSS が読み込めずに表示が崩れてしまった？ そんなときは慌てず、 _config_dev.yml などの名前で次の内容のファイルを作成します。

# url の指定を無効にする
url : ""

気を取り直して、次は --config _config.yml,_config_dev.yml オプションを付与してコマンドを実行し、再びブラウザで確認してみます。

bundle exec jekyll serve --config _config.yml,_config_dev.yml

このように、_config.yml の設定内容によってローカルでの表示確認に支障が生じる場合は、 ローカル用の config YAML ファイルを用意して設定を上書きして対処をします。

サイトの公開

ローカルの環境にてブラウザ経由での表示が確認できたら、いよいよ Github Pages への公開となります。

まずは公開に必要な HTML などを jekyll build コマンドで生成します。

bundle exec jekyll clean
bundle exec jekyll build

これで _site/ ディレクトリ配下に HTML などが出力されます。

続いて git リポジトリの構成を整理しておきます。今回は以下のブランチ構成とします。

  • master ブランチ
    • Jekyll のブランチに必要
  • source ブランチ
    • Github Pages で公開されるファイルのみを含んだリポジトリ

ここで、Github Pages での公開に必要なファイルのみを git リポジトリの master ブランチに含めるようにするため、以下の記事を参考に各種 git サブコマンドを実行します。

Github pages に 特定のディレクトリだけデプロイする

git add -f _site/
git commit -m "Add _site"
git subtree push --prefix _site/ origin master

これで所定のドメイン名 (カスタムドメインを利用していなければ http://your-github-name.github.io など) でアクセス可能なブログが公開されます。 めでたしめでたし。

You may also enjoy