お洒落にJekyllとGitHub PagesとMinimal Mistakesでホームページを作る

ホームページというもの

インターネット創世記、一般的な「ホームページ」は、プロバイダとダイアルアップ回線契約した時に、「ホームページ用のディレクトリ」を与えられ、そこに、「とほほのWWW入門」なんかを見ながら、秀丸でhtmlファイルを書いたりするものであり、また「ホームページビルダーを使ったりするのは邪道だ」とか自分勝手なことを呟くのが漢だと思っていた時代でもあります（要出典）。そして、昭和世代の私としては、この２０世紀末の風情を思い起こさせる「ホームページ」という単語と、これを「自分で作る」時間というのが、今でもすごく好きだったりします。

いまでは、簡単に情報発信できるブログシステムがたくさんあります。しかし、ブログと違ってホームページの良いところは、自分の好きなリンク構成、ページ構成に出来ることなのです。

さて、そんなホームページなのですが、今の最新ツールを使えば、htmlやCSSなんか全く書かず、簡素なマークダウンの書式で書くだけで、同じように簡素に書かれていると思われる有名な阿部ちゃんの「ホームページ」（阿部寛のホームページ）を遥かに凌駕する素晴らしいホームページが簡単に作れちゃうのです。（まぁ、軽さは負けるのですが）

ノートを読み進める前の試練

今回は、ArchLinuxを作業環境にして、 GitHubの「GitHub Pages」サービスを利用し、静的ウェブページ作成ツール「Jekyll」を使ってその有名なテーマである「Minimal Mistake」を利用してホームページを公開するためのノートです。

それぞれが割と有名ではあるので、それぞれのサービス自体の名前は何処かでなんとなく聞いたことがあるものだと思います。しかしながら、これらを有機的に繋げて使うためのまとまった情報が巷には少ない気がします。また、それぞれのサービスについての日本語の情報が断片的だったりします。そこで、これらを纏めて使うためのコツ的ノートを作っておくことにしました。（自分でもメンテのたびに、「あれなんだっけ？」するので）

但し、このノートの内容は、割とハードル高めな気がします。特に「ホームページを作る」というワードに引っかかってこのページを開いたインターネット初心者さんは、別の「ホームページを作る」を検索しましょう。

このノートでは、少なくとも、githubでの簡単な作業が出来ることが前提となります。といっても、githubにリポジトリを作成し、それをローカルにクローンして、編集し、コミットしてプッシュする程度です。

もし、git使ったことないけど、github pages等でのホームページ作りに興味が有る場合、まずは、ドットインストールを見てみましょう。全２２回ですが、みっちりとパーフェクトに理解する必要はありません。上記で言ったとおり、とりあえずは、コミットが出来て、なんとなくプッシュがわかればなんとかなるかもしれません。

git入門ドットインストール

これで、まだノートを読み進める気力があるならば、githubのアカウントも作っちゃってください。そして、以下のノートも参考にssh認証の設定もやっちゃってください！

gitとgithubをお洒落に使いこなす

そこまで出来たならきっと大丈夫。

じゃ、レッツゴー！！

RVMでRuby2の準備

「Jekyll」はRubyで動くので、Rubyの環境を準備する必要があります。

ここで、archlinuxの公式リポジトリのrubyのバージョンは既に、最新の3系統になっているのですが、実は、いまのところ、この最新バージョンの３系統では、 Jekyllを使ったgithub pagesのローカルプレビューで不具合がでます。一方、rubyにはユーザー側で、 rubyの複数のバージョンを切り替えて利用できる仕組みが用意されています。

そこで、このノートでは、バージョン切り替えの仕組みの一つである「RVM」を利用して、 Jekyllを快適に使えるrubyのバージョン２系統を使う方法を紹介します。

https://rvm.io/

RVMのインストール

RVMは、archlinuxのパッケージとしてインストールせず、 arch wiki のインストール手順に従い、 RVM公式ページから直接インストーラーをダウンロードして、自分でコマンドラインからインストールします。

まずは、以下のコマンドでインストールスクリプトをダウンロードします。

$ curl -L get.rvm.io > rvm-install

ダウンロードしたスクリプトの内容を確認したら、以下のコマンドで実行します。

$ bash < ./rvm-install

インストールスクリプトを実行すると、上記のようなメッセージが出ます。まず、RVMがインストールされる場所が明示されます。

Installing RVM to /home/neko/.rvm/

次に、RVMディレクトリ内のbinディレクトリを環境変数PATHに追加する設定を.bashrc等に追加した旨と、加工したファイル名が具体的に明示されます。上記のメッセージの中の以下のように書かれている部分がそれに該当します。

Adding rvm PATH line to /home/neko/.profile /home/neko/.mkshrc /home/neko/.bashrc /home/neko/.zshrc.

更に、RVMの関数定義スクリプトの読み込み指示を.profile等に追加した旨と、加工したファイル名が具体的に明示されます。上記のメッセージの中の以下のように書かれている部分がそれに該当します。

Adding rvm loading line to /home/neko/.profile /home/neko/.bash_profile /home/neko/.zlogin.

具体的には、関数定義スクリプトの読み込みのために、以下のような内容が.profile等に書き込まれます。

[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm"

ここで、.profileや.zloginファイルは、「ログインシェル」が立ち上がるときに読み込まれる設定ファイルなのですが、 lightDM等のログインマネージャを使ってログインすると、「ログインシェル」を起動することなく、 Xセッションとしてセッションがはじまるので、.profile等が読み込まれないということが起こることがあるようです。また、セッションの何処かでこのシェル関数の定義をしても、そのシェルから開かれた別のシェルに伝播しないこともあるようです。

そこで、まず、この設定が、うまく行っているかどうかをテストします。ここまでの作業を終えたら、一旦、ログアウトして、ログインし直します。システムの再起動でも構いません。

ログインし直したら、ターミナルを開いて次のコマンドを実行します。

$ type rvm

その結果が、以下のようにファイルを直接指している場合、残念ながら失敗です。関数定義のファイルが上手く読み込めていません。

$ type rvm
rvm is /home/neko/.rvm/bin/rvm

一方で、上手く読み込めている場合には、次のような表示になります。 rvmはシェル関数であると答えてくれます。

$ type rvm
rvm is a shell function from /home/neko/.rvm/scripts/cli

上手く行っていない場合、.zshrcや.bashrcに、下記の関数定義を直接読み込ませる設定を追加して様子を見ましょう。書き込む場所は、.rvm/binをPATHへ追加する設定が既に自動で書き込まれているはずなので、その直前に追加してあげましょう。

....
[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm"

# Add RVM to PATH for scripting. Make sure this is the last PATH variable change.
export PATH="$PATH:$HOME/.rvm/bin"

....

つまり、あんまりよくわからない場合は、とりあえず、自分の使ってる方のシェルの初期設定ファイル~/.bashrcか~/.zshrcの一番最後に、上記のコード（シェル関数の読み込みとパスの追加）をコピペしてみましょうってことです。そして、それから、一応、ターミナルを開き直して次の項目へ進んでみましょう。

--user-installは外してはいけない

RVMインストール時のメッセージをもう少し見てみると、以下のような記述があります。

WARNING: Found --user-install in /etc/gemrc, please remove it, as it will break rubygems in RVM.

これは、「/etc/gemrcに--user-installオプションをみつけました。RVMのrubygemsシステムを壊してしまうので、その設定を取り除いてください」という内容ですが、シングルユーザーモードでは当てはまりません。つまり「--user-installのオプションを絶対に外してはいけません」。

既に、環境変数GEM_HOMEが有る場合、外す

もともとrubyを利用していた場合、 archwikiの通りにやっていると、次のような感じで環境変数GEM_HOMEを設定していると思います。また、gemのbinディレクトリも${GEM_HOME}/bin等として、環境変数PATHに追加しているかもしれません。例えば、.bashrcには、次のような記述があるかもしれません。

#GEM_HOMEの設定
export GEM_HOME="$(ruby -e 'puts Gem.user_dir')"

#PATHへの追加
export PATH="$PATH:$GEM_HOME/bin"

環境変数GEM_HOMEは、バージョン管理の際にRVMのシステムが自動的に書き換えて面倒をみてくれます。そして、もし、自分の設定ファイルでGME_HOMEを定義していると、RVMの設定と衝突して不具合が起こる可能性があります。ですから、自分のシェル初期設定ファイルを見返して、自分でGME_HOMEを設定している箇所が有る場合、それを除外します。ちなみに、gemのbinディレクトリを自分で環境変数PATHへ通す必要もありません。RVMが面倒を見てくれます。

RVMでruby2.7をインストール

rvmコマンドを使って、ruby2.7をインストールします。

$ rvm install 2.7

インストールが終了したら、2.7をデフォルトで使うように設定します。

$ rvm use 2.7 --default

archlinuxのシステムのrubyを利用する場合は、以下で切り替え。

$ rvm use system

defaultに登録してあるもの（今は2.7）への切り替えは以下の通り。

$ rvm use default

2.7をデフォルトに一回設定しておけば、新しく開いたターミナルでは2.7が呼ばれるはずですが、以降、Jekyllを使う場面では事前に、rubyが2系統で動いているかを必ず確認してください。

RVMについて

このノートでは、ruby 2.x.xが使えればよいだけなので、ここまでの手順を踏めれば、十分です。 RVMにこれ以上深入りしませんが、興味の有る方は、下記から情報を辿ってください。

Jekyll

「Jekyll」は、マークダウンのような簡単な表記をするだけで、カッコいいウェブサイトを作成してくれるシステムです。

https://jekyllrb.com/

Jekyllのインストール

Jekyllはrubyのgemとして配布されています。早速、gemコマンドで、Jekyllとjekyllが使うbundlerを一緒にインストールします。しかし、このインストールの前に、そのターミナル内のrubyがバージョン2系統であることを確認しましょう。

$ ruby --version

もし、バージョンが３系統の場合、rvmを使って２系統に変更します。

$ rvm use 2.7

rubyのバージョンが２系統であることが確認できたら、以下のgemコマンドでjekyllとbundlerをインストールします。結構時間がかかるので、のんびりと待ちましょう。

$ gem install jekyll bundle

初めてのJekyll

まずは、実際に、Jekyllを使います。ここでは、Jekyllのページで紹介されている「Quick　Start」の手順を紹介します。ホームディレクトリ以下の適当なディレクトリで、以下のコマンドを発行しましょう。

$ jekyll new myblog

カレントディレクトリに「myblog」というディレクトリが作成されているはずなので、そのディレクトリに入ります。

$ cd myblog

このコマンドで、「myblog」というjekyllのプロジェクトが作成され、 myblogディレクトリの中には、jekyllを利用する上で必要となる設定ファイルと webコンテンツ用の初期サンプルファイルが準備されます。

myblogディレクトリに入って適当にファイルを確認したら、次は、以下のコマンドを実行します。

$ bundle exec jekyll server

jekyllには簡易なウェブサーバー機能が付属しているので、 jekyllで作ったwebページがどんなふうに風に見えるかをローカルでテストすることが出来ます。

メッセージの指示通り、自分のブラウザで「http://127.0.0.1:4000」へアクセスすると、 jekyllが作成したサイトを見ることが出来ます。

ここでは、ここまでの流れの通り、Jekyllが動作することが確認できればそれでOKです。

GitHub Pages

GitHub pagesは、githubのリポジトリにWebページ用のコンテンツを入れておくと、 Webページとして閲覧できるシステムです。

GitHub Pages用のリポジトリを作成する

Github Pageを利用する場合、リポジトリの名前が重要になります。あなたのユーザー名に入れ替えた「username.github.io」という名前のリポジトリを新規作成します。例えば、githubのユーザー名が「nekolinuxblog」ならば、「nekolinuxblog.github.io」という名前のリポジトリを作成します。

リポジトリのクローン

github Pages用のリポジトリが作成できたら、ローカルにクローンします。「gitとgithubをお洒落に使いこなす」で紹介している通り、ssh経由でクローンします。（リポジトリが空かどうかではじめの画面が異なります）

$ git clone git@github.com:nekolinuxblog/nekolinuxblog.github.io.git

usernameがnekolinuxblogの場合のURLは上記のようになります。そして、そのコマンドを実行すると、カレントディレクトリにリポジトリがクローンされます。

リポジトリにJekyllプロジェクトを作成

クローンしたリポジトリの中にJekyllのプロジェクトを作成します。リポジトリに入って、次のコマンドを実行します。最後のピリオドを見落とさないように。ピリオドでカレントディレクトリを指定しています。

$ cd nekolinuxblog.github.io
$ jekyll new --skip-bundle .

コマンドを実行すると、Jekyllプロジェクトとして必要なファイルが生成されます。

上記のコマンドを実行する際に、既にREADMEやライセンス等のファイルがあるとプロジェクト作成に失敗します。この場合、.gitディレクトリ以外の他のファイルを削除してから上記のコマンドを実行しましょう。

次は作成されたファイルの中にあるGemfileをエディタで開きます。

$ vim Gemfile

そして、次の編集を行います。

まず、ひとつめは、 gem "jekyll"で始まる行の行頭に#を書き加えて、コメントにする。

次に、コメント化した行の下に、以下の行を追加する。

gem "github-pages", "~> GITHUB-PAGES-VERSION", group: :jekyll_plugins

このとき、GITHUB-PAGES-VERSIONを特定のバージョンに置き換えなければなりません。何に置き換えるかは、Dependency versionsのページを開き、 Github Pagesのバージョンを調べて、それに置き換えます。ノート作成時点では219なので、以下のようになります。

gem "github-pages", "~> 219", group: :jekyll_plugins

つまりは、GitHubPagesの機能を使うために、通常のjekyll gemではなく、github-pages gemを使いますよと編集しています。編集完了したら、次のコマンドを実行しましょう。

$ bundle install

jekyllに必要なものがインストールされて準備されます。プロンプトが戻ったら、次のコマンドを実行しましょう。

$ bundle exec jekyll server

簡易サーバーが起動するので、http://127.0.0.1:4000にブラウザでアクセスしましょう。

github pagesに関連したJekyll構成の出来上がりです。見ているものは、先にローカルで作成した、Jekyllのサンプルと同じ内容ですが、これがGitHub Pagesとしてgithub上で機能します。なので、この状態をコミットしてgithubへプッシュすると、そのまま、Webページとして公開されます。 Ctrl+Cで簡易サーバーを終了したら、早速、コミットしてプッシュです！

pushしてから、Webページとして反映されるのに数分かかります。 URLは、https://username.github.io/です。usernameを自分のgithubアカウントのユーザー名に置き換えましょう。僕のURLは、https://nekolinuxblog.github.io/です。

ここまでで、GitHubPagesとJekyllの連携の一例ができました。 Jekyllを使って自分のページデザインをしてみたい場合は、ここがスタート地点になります。

Minimal Mistakes

Minimal Mistakesは、Jekyllの機能を使ってデザインされたテーマです。

https://mmistakes.github.io/minimal-mistakes/

Minimal Mistakes用の設定ファイル等をコピーして、自分用のカスタマイズの雛形にするのが便利なので、まずは、下準備として、Minimal Mistakesのgithubリポジトリをクローンしておきます。適当なディレクトリのもとで以下のコマンドを実行しましょう。

$ git clone https://github.com/mmistakes/minimal-mistakes.git

自分のリポジトリを空にして１からやり直し

さて、先に自分で作成したGitHubPages用のリポジトリの中身を.gitディレクトリを除いて空にします。つまり、先に試したJekyllサイトを消して、最初にクローンしてきた時の空っぽの状態に戻します。このノートでは、GithubPagesでのJekyllの連携の確認のために、Jekyllの雛形サイトを上記で作成しましたが、実際に、Minimal Mistakesを使ってサイトを構築する場合、先の手順は必要ありません。 GitHubPages用の空のリポジトリを用意したら、ここの手順からスタートしてOKです。

リポジトリが空になったら、最初に、以下の内容のGemfileを作成しましょう。

source 'https://rubygems.org'
gem 'github-pages',"~> 219", group: :jekyll_plugins
gem 'jekyll-include-cache', group: :jekyll_plugins

先に紹介したとおり、github-pagesの後ろにある219の部分は、Dependency versionsのページを開き、 Github Pagesのバージョンを調べて、それに置き換えます。

Gemfileの編集が出来たら、次のコマンドでgemをインストールします。

$ bundle install

次は、クローンしたminimal mistakesのリポジトリのトップディレクトリにある次の３つのファイルを自分のGitHubPagesのリポジトリにコピーします。

.gitignore
_config.yaml
index.html

コピーしたファイルのうち、_config.yamlをエディタで開きます。そして、「# remote_theme :..」で始まる行の行頭の#を外してコメント化を解きます。

....
remote_theme : "mmistakes/minimal-mistakes"
....

以上で、準備が完了しました。次のコマンドで簡易サーバーを立ち上げ、ブラウザで確認してみましょう。

$ bundle exec jekyll server

これでMinimal Mistakesが動くようになりました。

このリポジトリをpushすることで、GitHubPagesとして、Webサイトを公開することが出来るようになります。

リポジトリのメンテナンス

rubygemを使ったjekyllのシステムは、常にgemがアップデートされていきます。古いgemのままほったらかしているとセキュリティ上の問題がある場合があります。そこで、定期的にgemに新しいものを使うようにbundleでアップデートを行います。リポジトリに入って、以下のコマンドを実行しましょう。

$ bundle update

Home pageの作り方の基本

Jekyllシステムには、核になる"_config.yaml"という名前の設定ファイルと自分で作るコンテンツ用のファイルがあります。

_config.yaml

Jekyllシステムは、"_config.yaml"ファイルで全体の設定を行います。 yamlファイルは基本的に「key:値」という書式になっています。この設定ファイルでは、このホームページ全体の挙動の設定もおこないますが、 Jekyllでは、これらのkeyが変数としてテンプレートに書き込まれており、その内容が設定された値に置き換えられてコンテンツページが作成される仕組みになっています。まずは、_config.yamlを開いて、「#site Settings」辺りの、titleやnameについての値を書換えてみましょう。

...
# Site Settings
locale                   : "en-US"
title                    : "おしゃれなほーむぺーじ"
title_separator          : "-"
subtitle                 : # site tagline that appears below site title in masthead
name                     : "猫田しゅん吉"
description              : "ホームページで世界をおしゃれにする"
...

その他に、もう少し下にある「Site Author」の辺りも、自分の名前にしてみましょう。

...
author:
  name             : "Nekota"
  avatar           : # path of avatar image, e.g. "/assets/images/bio-photo.jpg"
  bio              : "猫になりたい"
  location         : "Osaka Japan"
  email            :
...

自作のマークダウンファイル

コンテンツファイルは、通常のhtmlではなく、マークダウン書式で書くことが出来ます。また、自作のマークダウンファイルは、そのファイルの始まりに「---」と「---」で囲まれた「yamlフロントマター」と呼ばれる yaml書式設定を書き込んだ部分を持っています。

先に準備したindex.htmlファイルを開いて内容を見てみましょう。拡張子に.htmlを使っていても、jekyllでは、コンテンツファイルとして処理してくれます。

---
layout: home
author_profile: true
---

layoutの値は、homeになっていますが、この部分を切り替えることで、minimal mistakesページの用途（見た目の体裁）を切り替えることが出来るようになっています。 minimal mistakesで定義されている主なものは、以下のとおりです。（詳しくは、Layout based and user-defined classesを参照）

home
single
posts
splash
search
category

author_profileについては、trueとfaulseの値を入れ替えて、実際にどのような変化があるのかたしかめてみましょう。このように、yamlフロントマターで、コンテンツページの設定を行えるようになっています。

そして、ページのコンテンツ自体は、yamlフロントマターの後ろに、マークダウン形式で記述します。

コンテンツファイルの置き場所とファイル名

自分で作成するコンテンツファイルは基本的にリポジトリのルートディレクトリにあればhtmlファイルへ変換されます。 jekyllでは、変換されたファイルは"_site"ディレクトリに出力されます。

一方、minimal mistakesでは、自作のコンテンツファイルについて、置き場所が決められているものがあります。その中でも投稿記事形式のコンテンツは"_posts"ディレクトリに配置するようになっています。また、ファイル名も「YEAR-MONTH-DAY-title.MARKUP」という形式でつけるようになっています。例えば、「2022-01-04-happyday.md」という感じです。

また、一般的なページについては、"_pages"ディレクトリに置きます。例えば、about.mdや404.mdがここに置かれます。

Jekyllシステムでは、コンテンツファイルの置き場やフィル名によって、実際のWebのコンテンツ構成や投稿の検索などを行う仕組みになっているので、そのテーマで説明されている約束ごと通りにコンテンツファイルを構成することが必要になります。

読むべき場所

ここまでで、実際にGitHub Pages上で、Jekyllシステムが動く環境を手に入れることが出来、また、Jekyllシステムがざっくりと、どんな仕組みになっているということを把握しました。あとは、実際に、触りながら覚えてきましょう。その時に、必要となる知識はまず、Jekyllの日本語ページです。

Step by Stepでは、liquid（リキッド）という仕組みを利用して、変数での置き換えや場合分け、フィルタ機能を使って、テンプレートを作成しているJekyllの大まかな仕組みがわかるようになると思います。次にディレクトリ構成でjekyllのプロジェクトディレクトリ内にある一般的なファイルやディレクトリの役割がわかります。そして、PagesやPostsでJekyllシステムのコンテンツを具体的にどうやって配置するかも解るようになると思います。最後に、パーマリンクによって、各コンテンツファイルとリンク関係や実際のURLでどんな風に構成するかを調整する仕組みが分かるようになります。

基本的なJekyllのシステムがわかった上で、これを使って具体的にデザインされたminimal mistakesを実際に使うためには、 minimal mistakesのドキュメントを読む必要がありますが、現在のところ、ドキュメントは英語のみです。また、ドキュメントの量も多く、構成も複雑なので、英語を読むのが苦痛な人にとっては大変な作業になります。

そこで、まずは、次のページに的を絞って目を通しましょう。ひとつめは、_config.yamlに定義されている各キーについての説明をしているページです。サイトの動作に関する調整や、コメント機能の追加等、難しそうなところは飛ばして、 titleやnameのような値を正しく設定することで、サイトのアチコチの紐付けられた部分が正しく表示されるようにしましょう。

https://mmistakes.github.io/minimal-mistakes/docs/configuration/

次に、minimal mistakesで定義されている「layout」と各レイアウトで取ることが出来るオプションを知ることが出来るページです。

https://mmistakes.github.io/minimal-mistakes/docs/layouts/

英語がよくわからなくても、yamlフロントマーターの例と、スクリーンショットがあるので、実際に試しながら理解することが出来ると思います。特に、次のレイアウト項目に着目してみてください。