ポートフォリオっぽいサイトをGitHub Pages + Jekyll構成に移行した話

久しぶりの投稿です。

今回、個人の実績とかを集約していたサイトをリニューアルしたので、その手順をメモしておきます。

このサイト自体は大学院の研究室の都合で作成したものだったのですが、 その時々の技術的な流行をちょっと試してみるみたいな趣旨もあり、 構成もHerokuやAWSと10年の間でいろいろ変遷してきました。 完全にオーバースペックなので、もっと一般的な手法に切り替えます。

なお、移行とリニューアルが完了したサイトは以下になります。

https://mikinya.net/

今回の動機

今回、サイトを移行・リニューアルするモチベーションをまとめると以下になります。

  • 勉強のためにnode.jsやAWS、コンテナを使っていたが、今は目的を果たして単にオーバースペックで複雑
  • 特に専用のフレームワークなどは活用してないのでページ追加がやりにくい
  • もはやBootstrapが古く見えすぎる
  • 極微量な料金だが、無料でできるのなら節約したい

ということで、単にインフラのレイヤーを移行するというより、 見栄えやフレームワークまで意識していく流れです。

前回までの話

当該サイトは2019年1月にHerokuの環境からAWS/Docker/Elastic Beanstalk環境へ移行しました。 その時の記事がこちらです。

mikimemo.hateblo.jp

*ちなみに上記記事のFargateの見解はおもいっきし間違いです。そもそもFargateはコンピューティング・リソースを提供するもので、単純にECSとかと比較するのは検討違いでした。

約3年この構成で動いていたのか... 実は去年RIの購入とかもしていたりして、とても勉強になりました。ありがとう旧構成。

作業の方針

色々調査した結果、 GitHub PagesJekyllを利用することにしました。

Jekyllはマークダウン記法のドキュメントなどから、 いい感じに静的なWebサイトをジェネレートしてくれるライブラリです。

もともと、簡単にWebコンテンツをホスティングできる、かつ独自ドメインも設定可能な GitHub Pagesを利用しようとは決めていたのですが、 ドキュメントを読み進めていくうちに、Jekyllというものを知り、いいやん!となりました。

メモ: 静的サイトジェネレーターは世の中にたくさんあると思いますが、 今回はGitHub Pagesが公式対応しているのでJekyllにフォーカスです。

こちらの比較記事参考になります。

プロジェクト生成、ローカル確認

GitHub側のリポジトリ作成などは、済ませているとしてローカルにJekyll環境を構築してきます。

基本GitHub PagesやJekyllの公式手順に従っていきます。

docs.github.com

jekyllrb-ja.github.io

まずは、ローカルにリポジトリ用のディレクトリ作ります。

$ mkdir my-site
$ cd my-site

*ライブラリ開発とかですでにリポジトリ内に何かある場合はorphanブランチとかに作ったりすると良さそう

初期化に必要なgemをインストールして初期ファイルを生成します。

$ gem install bundler jekyll
$ jekyll new --skip-bundle .

Gemfileのjekyllの部分をコメントアウトしてgithub-pagesの項目に変更します。 このとき223のところはこのページから都度対応している最新バージョンに置き換えてくれとのことです。

#gem "jekyll", "~> 4.2.1"
gem "github-pages", "~> 223", group: :jekyll_plugins

これでbundle installします。

$ bundle install

完了したら以下でローカルサーバーを立ててみます。 http://localhost:4000にアクセスすると、それっぽいサイトが立ち上がっていることを確認できます。

$ bundle exec jekyll s

f:id:miki05:20220228205505p:plain

リモートでの確認

一旦この辺りでremoteにpushしてGithub Pagesの動作を確認してみると良いでしょう。 ただし、GitHub Pagesのデフォルトでは以下みたいな感じでサブフォルダにホストされるため、 あらかじめ設定をしておかないと、うまく表示されないケースがあります。

https://account-name.github.io/repo-name/

これらの設定のためにプロジェクト直下にあるconfig.ymlを編集します。 Jekyllではこのconfig.ymlがキモで、 このファイルに様々な定義や設定を指定することで、 全体の見栄えや動作をカスタマイズしていきます。

以下の項目を修正します。

url: https://[GitHub Account Name].github.io
baseurl: /[Repository Name]/

最終的には独自ドメインを設定するので、この設定は不要なのですが、 一時的に設定して、サイトの移行準備が完了したら再度修正します。

ちなみにですが、リポジトリのRoot DirectoryにREADME.mdを配置していると、 GitHub Pagesにデプロイした時、なぜかそれをトップページみたいな感じで認識されます。

こちらは_config.ymlのexcludeの項目のコメントアウトをはずしてREADME.mdを追記するとJekyllの処理対象外にできます。

exclude:
  - .sass-cache/
  - .jekyll-cache/
  - gemfiles/
  - Gemfile
  - Gemfile.lock
  - node_modules/
  - vendor/bundle/
  - vendor/cache/
  - vendor/gems/
  - vendor/ruby/
  - README.md #追記

自分の場合、作業観点でのmemoなどをREADMEに残しておきたかったので、このような処置をとりました。 Jekyllの構成フォルダをサブフォルダとかに切り出す設定なども試しましたが、あんまりうまくいかなかったです。

テーマの設定

Jekyllはサードパーティ製のものも含めてさまざまなテーマを利用できます。 今回は一番スターがついていて良さそうな感じのMinimal Mistakesを利用することにしました。

mmistakes.github.io

またテーマのライブラリごとにお作法が変わってきたりもするので、 以後はMinimal Mistakesのドキュメントも必読です。

とりあえず、テーマ導入します。 複数の方法があるようですが、今回はremote_themeを利用する方法にします。

ますGemfileに以下を追記してbundle installします。

gem "jekyll-include-cache", group: :jekyll_plugins

次に_config.ymlを修正します。skinも選べるので後でゆっくり検討するとよいです。

# theme: minima # 消す 
remote_theme: mmistakes/minimal-mistakes@4.24.0
minimal_mistakes_skin: "default" #"air", "aqua", "contrast", "dark", "dirt", "neon", "mint", "plum", "sunrise"

plugins:
  - jekyll-feed
  - jekyll-include-cache # 追加

多分これでサーバー立て直すとテーマが適用されているかと思います。 ちなみに基本Jekyllはコンテンツを修正すると自動でhtmlファイルなどを再ジェネレートしてくれるんですが、 configファイルを修正したときはサーバー再起動が必要のようです。

f:id:miki05:20220228205603p:plain

レイアウトとFront Matter

テーマを変更後、サーバーのたてる時にいくつかのワーニングがでており、 例えばabountなどのページがうまく表示されなくなります。

これは、デフォルトのテーマではpageというレイアウトが存在していたのですが、 Minimal Mistakesに変更したことでそのレイアウトが存在しなくなってしまったためです。 これらのレイアウトは各マークダウンファイルの冒頭で指定ができます。 layoutでpageが指定されているところをsingleに変更します。

---
layout: page # -> single
title: About
permalink: /about/
---

# 本文...

この冒頭のハイフンで囲まれた領域をFront Matterと呼び、 ページごとにさまざまな指定ができます。

config.ymlなどをいじくる

この辺りで_config.ymlやファイル構成を用途に合わせて修正していきます。 今回はabout.markdownやpost(ブログのような記事を管理できる機能)などの要素は不要のため、ファイルを削除しました。 また.markdownの拡張子も.mdに統一しました。

Authorの表示

今回はポートフォリオサイトみたいなものを作りたいので、自分の情報を表示するために Authorの機能を利用しました。これを使うとページの左側に情報を表示することができます

以下のように_config.ymlに追記します。

author:
  name: "Mikito Yoshiya"
  avatar: "/assets/img/avatar.png"
  bio: "Software Engineer"
  location: "Tokyo, Japan"
  links:
    - label: "Blog"
      icon: "fas fa-fw fa-link"
      url: "https://mikimemo.hateblo.jp"
    - label: "Twitter"
      icon: "fab fa-fw fa-twitter-square"
      url: "https://twitter.com/mikito0521"
    - label: "Facebook"
      icon: "fab fa-fw fa-facebook-square"
      url: "https://www.facebook.com/mikito.yoshiya"
    ...

画像などのファイルはassetsなどのフォルダに配置しておけば、 Jekyllが自動的に認識して、成果物フォルダである_siteにコピーし参照できるようにしてくれます。

ちなみに各サービスのアイコンはドキュメントにもありますがこちらで利用可能なものを検索できます。

この設定後各ページのFront Matterで

author_profile: true

とすると、有効になります。

defaultsの設定

author_profileの設定は各ページのFront Matterで指定すれば有効になりますが、 全てのページで指定するのは面倒です。

config.ymlではパスごとにFront Matterのデフォルト値を設定できます。 基本的なページではauthor_profileを有効に、layoutはsingleを利用するようにしておきます。

defaults:  
  - scope:
      path: ""
      type: pages
    values:
      layout: single
      author_profile: true

Feedはいらない

今回はFooterのRSSフィードのリンクは不要だったので、 以下のように非表示しました。

atom_feed:
  hide: true

その他

その他navigationとかfooterとかめちゃくちゃ機能があるのですが、 公式ドキュメントを読みながら進めるのがよいと思います。

今回は、超シンプルなサイトを構築するのが目的のため上記あたりの設定で完了です。

あとはindex.mdとか必要なページをマークダウンで記述していきます。 この辺りのドキュメントも参考になります。

独自ドメインの設定

基本はGitHub Pagesの公式手順に従っていきます。

GitHub上でSettings->PagesのCustom domainに取得済みドメインを入力してSaveを押します。 そうするとリポジトリにCNAMEという名前のファイルが自動的にコミットされます。

次にDNS側の設定をします。 自分の場合ドメイン自体はお名前.comで取得しています。 また、旧構成ではAWSのサービスに管理を寄せており、 DNSサービスにRoute 53を利用していたのですが、 そちらでの管理は廃止しお名前.com側に登録するようにします。

これに関しては、こちらの記事を参考にさせていただきました。

上記の手順だけでは、Github Pagesがワーニングを吐いてきたので、 お名前.comのインターフェースからwwwサブドメインのCNAMEレコードも登録しました。

CNAME www.my-site.net github-account-name.github.io

設定が完了しGitHub Pages上でcheckがpassしたらEnforce HTTPSも有効にしておきます。

faviconの設定

一応ですがfaviconの設定もしました。

faviconっていまの世の中すごい面倒なことになってるんですね... faviconを設定するためにはJekyllのレイアウトテンプレートを修正する必要があるんですが、 そこにはrealfavicongenerator.netというサービスを使ってくれと記述されています。

realfavicongenerator.net

こちらは一つのソースとなる画像をアップロードすると、必要な素材をプレビューしながら一括で作ってくれるし、 配置するためのコードスニペットも出力してくれるし、 さらにサイトのfaviconが様々なデバイスで正しく表示されるかをチェックしてくれるという神ツールです。

今回faviconも一新しようと思い新しく適当に書きました。 (今の自分はレベル1だけど簡単なベクター画像が描ける...!)

適用の手順はこちらを参考にさせてもらいました。

まず、リポジトリに_includes/head/というディレクトリを作ります。 そして、custom.htmlを配置します。 こちらは、本来ライブラリ側のソースをオーバーライドする形なのでリポジトリとかからコピーしてくるのが良さそうですが、 customと書かれているものはコメントのみのようなので、直接ファイルを作成しても良さそうです。

そして、そのファイルにrealfavicongenerator.netで出力された情報を貼り付けます。 この時、変換されたアイコン群は数が多いため、自分は整理の意味でassets/icon以下に配置しました。 そのため、hrefの部分を置き変えています。こちらの変更はbrowserconfig.xmlとsite.webmanifestの内容に対しても同様です。 また、browserconfig.xmlとsite.webmanifestに関してはその立ち位置上、サイトのルートに配置するようにしました。

<link rel="apple-touch-icon" sizes="180x180" href="/assets/icon/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/assets/icon/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/assets/icon/favicon-16x16.png">
<link rel="manifest" href="/site.webmanifest">
<link rel="mask-icon" href="/assets/icon/safari-pinned-tab.svg" color="#5bbad5">
<meta name="msapplication-TileColor" content="#da532c">
<meta name="theme-color" content="#ffffff">

設置後https://realfavicongenerator.net/ でチェックします。 オールグリーンになればOKです。

旧環境のストップ

移行確認完了後、旧環境の停止作業を行います。

  • Route 53/ホストゾーン削除
  • Elastic Beanstalkの環境削除

Elastic Beanstalkに関してはDockerのプラットフォームが もれなくDeprecatedなってました。 今回の作業でこのような管理もフルマネージドに移行できるのはとても楽です。

その他、今回の作業の動機の一つですが、RIが2022/2/21で切れてます。 t3.nanoのRIなんて他に誰が使うんでしょうね...

コストとしては旧環境は合計で月$3.2程度でした。

その他の関連サービスも確認しましたが、問題なさそうでした。

  • EC2
  • ECS
  • ECR

作業を終えて、最後に

ひとまず移行とリニューアルが完了してひと段落です。 旧構成であるAWSサービスやコンテナを利用した取り組みは、とても勉強になるものでした。 ミニマムなものであっても実際に公開するところまでやっていくと、 ドキュメントを読むだけではわからない体験があります。

ただ、旧構成はコスト極限まで切り詰めるという方針から、 SSL証明書の管理周りがかなりテクっていて汎用性はなさそうでしたけど。

別の機会でAWSを使いこなして何かちゃんとサービスを自分自身で作ってみたいなーと思ったりしました (なかなか仕事では触れる機会がない)。

あとGitHub Pages、Jekyll、Minial Mistakesは可能性を感じました。 またどこかで活用する時がある気がします。

そして、サイト自体ですが、 本当は最初、学生時代の論文とか載せるのやめようかなと思ってましたが、 当時すごく頑張って仕上げた(&賞もいただいた)ことを思い出して、 引き続き掲載することにしました。

趣味で作ってたケーキ画像は廃止しました。

そして去年6月に執筆したUnity2021 3D/2Dゲーム開発実践入門のリンクも追記しました (ソシムさん全然宣伝できず、すみません。。。)。 こちら改訂作業も相変わらず苦労したので、ご興味あればぜひ覗いてみてください。

せっかくリニューアルしたのでポートフォリオを充実できるよう、 今後はもっともっとアウトプットしていきたいです!