Post

GitHub Pagesブログの作成と管理

静的ウェブページと動的ウェブページの特徴と違い、静的ウェブサイトジェネレーター（Static Site Generator）について学び、JekyllブログをGitHub Pagesにホスティングしてみよう。

Posted Updated
Preview Image
By Yunseo Kim
views 26 min read
GitHub Pagesブログの作成と管理

人類紀元 12021年初めからJekyllを使ってGitHub Pagesにブログをホスティングし始めました。しかし、ブログ構築時にインストール過程を適切に整理しておかなかったため、後の維持管理に少し困難があったので、簡単にでもインストール過程と維持管理方法を整理しておくことにしました。

（+ 12024.12 内容更新）

1. 静的サイトジェネレーター＆ウェブホスティング

1-1. 静的ウェブページ vs 動的ウェブページ

静的ウェブページ（Static Web Page）

  • サーバーに保存したデータをそのままユーザーに配信するウェブページ
  • ウェブサーバーでユーザーのリクエストに該当する予め保存しておいたページを配信する
  • ユーザーはサーバーに保存されたデータが変更されない限り、同じウェブページを見ることになる
  • リクエストに該当するファイルだけを送信すればよいので、追加作業が不要であり、一般的に応答が速い
  • 単純なファイルだけで構成されているため、ウェブサーバーだけを構築すれば良く、構築コストが安い
  • 保存された情報だけを表示するため、サービスが限定的
  • データの追加、修正、削除を管理者が手動で行う必要がある
  • 検索エンジン側からクローリングしやすい構造で、検索エンジン最適化（SEO）に相対的に有利

動的ウェブページ（Dynamic Web Page）

  • サーバーに保存したデータをスクリプトで加工処理して配信するウェブページ
  • ウェブサーバーでユーザーのリクエストを解析してデータを加工した後、生成したウェブページを配信する
  • ユーザーは状況、時間、リクエストなどによって変わるウェブページを見ることになる
  • ウェブページ配信のためにスクリプトを処理する必要があるため、相対的に応答が遅い
  • ウェブサーバー以外にアプリケーションサーバーが必要なため、構築時に追加コストが発生する
  • 様々な情報を組み合わせて動的に提供するため、多様なサービスが可能
  • ウェブページ構造によっては、データの追加、修正、削除をユーザーがブラウザから行うことができる

1-2. 静的ウェブサイトジェネレーター（SSG, Static Site Generator）

  • 生データ（通常はmarkdown形式のテキストファイル）と事前定義されたテンプレートに基づいて静的ウェブページを生成するツール
  • 個別のHTMLページを直接作成する必要なく、マークダウンで投稿を作成すればウェブページをビルドしてウェブ上に配布する過程を自動化する
  • 例）Jekyll、Hugo、Gatsby、Eleventy

1-3. GitHub Pages

  • GitHubが無料で提供する静的ウェブページホスティングサービス
  • アカウントごとに1つの個人代表ウェブページをホスティングでき、無制限にリポジトリ別プロジェクト文書ページを作成・ホスティングできる
  • ‘{username}.github.io’形式の名前で自分のGitHub usernameに合わせてリポジトリを作成した後、そのリポジトリにビルドしたHTMLページを直接Pushするか、またはGitHub Actionsを活用してビルドおよび配布を行うことができる
  • 所有しているドメインがあれば設定で接続して、’{username}.github.io’形式の基本ドメインの代わりに別のドメインアドレスを使用することもできる

2. 使用するSSGとテーマの選択

2-1. Jekyllを選んだ理由

Jekyll、Hugo、Gatsbyなど様々なSSGが存在しますが、Jekyllを使用することに決めました。使用するSSGを選択する過程で考慮した基準と、Jekyllを選んだ理由は次の通りです。

  • 不必要な試行錯誤を最小限に抑え、記事作成とブログ運営に集中できるか？
    • JekyllはGithub Pagesで公式にサポートされている静的ウェブサイトジェネレーターです。もちろんHugo、Gatsbyなど他のSSGもGithub Pagesでいくらでもホスティングできますし、Netlifyなど全く別のホスティングサービスを利用するという選択肢もありますが、実際このくらいの規模の個人ブログを運営する上で、技術的にどのSSGを使用して構築したかやビルド速度、パフォーマンスなどはあまり重要ではないので、少しでもメンテナンスが簡単で参考にできる文書が多いものが良いと判断しました。
    • Jekyllはまた、Hugo、Gatsbyなど他の競合に比べて開発期間が最も長いです。それだけ関連文書化がよくされており、実際に問題が発生した時に参考にできる資料の量が圧倒的に多いです。
  • 使用できるテーマとプラグインが多様か？
    • 直接HTMLを作成するのではなくSSGを使用するとしても、各種テンプレートを直接作るのは面倒で時間もかかり、あえてそうする必要もありません。ウェブ上ですでに公開されている優れたテーマが多いので、気に入ったものを採用して活用すれば良いです。
    • さらに私はもともとCやPythonを主に活用するため、JekyllのRubyやHugoのGo言語はあまり詳しくない状況だったので、既存に開発されているテーマとプラグインを積極的に活用しようと考えました。
    • Jekyllには一目見て気に入るテーマをすぐに見つけることができましたが、HugoやGatsbyは相対的に個人ブログ目的で使うのに適したテーマの数がそれほど多くなかったようです。おそらく上述したように、開発者たちが個人ブログホスティングのために多く使用するGithub Pagesとの連携性、そして開発期間がここにも大きく影響したようです。

2-2. テーマ選択

Minimal Mistakes (12021.01 - 12022.04)

  • Github Repo: https://github.com/mmistakes/minimal-mistakes
  • Demo Page: https://mmistakes.github.io/minimal-mistakes/
  • ブログを最初に作って約1年3ヶ月間活用していたテーマ
  • Disqus、Discourse、utterancesなどを通じたコメント機能をサポート
  • カテゴリーとタグ分類機能をサポート
  • Google Analytics基本サポート
  • 事前定義されたスキン選択可能
  • デザインがより洗練されていて気に入ったChirpyテーマをその後発見して移行しましたが、どうせエンジニアらしいブログということを考えると、美しくなくても比較的すっきりしたデザインを持っていて無難に使えたと思います。

Chirpy Jekyll Theme (12022.04 - 現在)

  • Github Repo: https://github.com/cotes2020/jekyll-theme-chirpy/
  • Demo Page: https://chirpy.cotes.page/
  • 12022年4月にブログテーマを移行して以来、現在まで使用中のテーマ
  • 複数カテゴリー分類、タグ機能サポート
  • MathJaxベースでLaTex文法の数式表現を基本サポート
  • Mermaidベースのダイアグラム機能を基本サポート
  • Disqus、Giscusなどを通じたコメント機能サポート
  • Google Analytics、GoatCounterサポート
  • ライトテーマとダークテーマサポート
  • テーマ切り替え時点の基準でMathJaxやMermaidはMinimal Mistakesテーマでは自体サポートしておらず、直接カスタマイズで追加する必要がありましたが、Chirpyテーマでは基本的に自体サポートしています。もちろんカスタマイズと言っても大したことはないですが、それでも小さな利点と言えます。
  • 何よりも、デザインが美しいです。Minimal Mistakesテーマはすっきりしていますが、何かブログというよりプロジェクト公式技術文書やポートフォリオページにより適しているような特有の硬さがありますが、Chirpyテーマはティストリーやミディアム、velogなどの商用ブログプラットフォームと比較しても遜色ないデザインが長所です。

3. GitHubリポジトリの作成、ビルドおよび配布

現在（12024.06）使用中のChirpy Jekyll Themeを基準に記述し、Gitは基本的にインストールされていると仮定して進めます。
Jekyll公式インストールガイドとChirpy Jekyll Theme公式ページを参照。

3-1. Ruby＆Jekyllのインストール

Jekyll公式インストールガイドに従って、自分のオペレーティングシステム環境に合わせてRubyとJekyllをインストールします。

3-2. GitHubリポジトリの作成

Chirpy Jekyll Theme公式ページでは次の二つの方法を紹介しています。

  1. “jekyll-theme-chirpy” gemで核心ファイルを読み込み、残りのリソースをChirpy Starterテンプレートから取得する方法
    • 長所：後述しますが、バージョンアップグレードの適用が容易です。
    • 短所：カスタマイズが制限されます。
  2. jekyll-theme-chirpyリポジトリを自分のブログのリポジトリにフォークする方法
    • 長所：すべてのファイルをリポジトリ内で直接管理するため、テーマでサポートしていない機能も直接コードを修正して自由にカスタマイズできます。
    • 短所：バージョンアップグレードを適用するには原本リポジトリの最新アップストリームタグをマージする必要がありますが、場合によっては直接カスタマイズしたコードがアップグレードバージョンのコードと衝突する可能性があります。この場合、該当する衝突を直接解決する必要があります。

私は1番の方法を採用しました。Chirpyテーマの場合、基本的に完成度が高いため、ほとんどのユーザーの立場では大してカスタマイズするものがないうえ、12024年現在でもかなり活発に開発および機能改善が進行中なので、よほど大幅な改造をするのでなければ、原本アップストリームをタイムリーに追従することのメリットが直接カスタマイズを適用することのメリットを上回ります。Chirpyテーマ公式ガイドでもほとんどのユーザーには1番の方法を推奨しています。

3-3. 主要設定

ルートディレクトリの_config.ymlファイルと_data/contact.yml、_data/share.ymlファイルで必要な設定を適用します。コメントがよく付けられており、設定が直感的なので特に困難なく適用できます。そのうち外部で別途の作業が必要な設定としてGoogle Search Console連携のための認証コード登録やGoogle Analytics、GoatCounterなどのウェブマスターツール連携程度がありますが、これも実際にはそれほど複雑な手順ではなく、この記事で扱おうとする核心テーマではないため、詳細な説明は省略します。

3-4. ローカルでビルドする

必須手順ではありませんが、新しい投稿を作成したり、サイトに何か修正を加えたりした時に、ウェブで正常に表示されるかどうかを事前に確認したい場合があります。このような場合は、ローカルリポジトリのルートディレクトリでターミナルを開き、以下のコマンドを実行します。

1

$ bundle exec jekyll s

数秒ほど待つとサイトがローカルでビルドされ、http://127.0.0.1:4000アドレスで結果を確認できます。

3-5. 配布する

二つの方法があります。

  1. GitHub Actionsの活用（GitHub Pagesでホスティングする場合）
    • GitHub Free Planを使用中であれば、リポジトリをpublicに維持する必要があります
    • GitHubウェブページでリポジトリのSettingsタブを選択した後、左側のナビゲーションバーからCode and automation > Pagesをクリックし、SourceセクションでGitHub Actionsオプションを選択します
    • 設定完了後、新しいコミットをPushするたびにBuild and Deployワークフローが自動実行されます
  2. 直接ビルドして配布（他のホスティングサービスを活用するか、セルフホスティングする場合）
    • 以下のコマンドを実行して直接サイトをビルドします
      1

        $ JEKYLL_ENV=production bundle exec jekyll b
    • _siteディレクトリにあるビルド結果をサーバーにアップロードします

4. 投稿作成

Chirpyテーマの投稿作成ガイドに投稿作成方法と使用できるオプションがよく文書化されています。この記事で述べること以外にも様々な機能を提供しており、参考になる内容なので、必要であれば公式文書を参照してください。ここでは毎回投稿するたびに共通して念頭に置くべき主要事項をまとめておきます。

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

  • 名前形式：YYYY-MM-DD-TITLE.md
  • 場所：_postsディレクトリ

Front Matterの作成

マークダウンファイルの最初の部分にはFront Matterを適切に作成する必要があります。

---
title: TITLE
description: >-
  DESCRIPTION
date: YYYY-MM-DD HH:MM:SS +/-TTTT
categories: [TOP_CATEGORIE, SUB_CATEGORIE]
tags: [TAG]
image:
  path: /path/to/image
  alt: image alternative text
toc: true
comments: false
math: true
mermaid: true
---
  • title：投稿タイトル
  • description：要約文。作成しない場合、本文内容の前部分の一部を自動的に取得して使用しますが、検索エンジン最適化（SEO）のためにはdescriptionメタタグを直接適切に作成することをお勧めします。ローマ字基準で135～160文字、日本語基準で80～110文字程度の分量が適切です。
  • date：正確な投稿作成日時とタイムゾーン（省略可能、省略時はファイルの作成日または修正日情報を自動的に認識して使用）
  • categories：投稿のカテゴリー分類
  • tags：投稿に適用するタグ分類
  • image：投稿上部にプレビュー画像挿入
    • path：画像ファイルパス
    • alt：代替テキスト（省略可能）
  • toc：右側サイドバーの目次機能使用有無、デフォルト値はtrue
  • comments：サイト基本設定とは別に、個別投稿のコメント使用有無を明示的に指定したい場合に使用
  • math：内蔵されたMathJaxベースの数式表現機能を有効化、デフォルト値はページパフォーマンスのために無効化（false）
  • mermaid：内蔵されたMermaidベースのダイアグラム表現機能を有効化、デフォルト値は無効化（false）

5. アップグレード

3-2で1番の方法を採用したと仮定して説明します。2番の方法を採用した場合は、上述したように最新アップストリームタグを直接マージする必要があります。

  1. Gemfileを編集して”jekyll-theme-chirpy” gemのバージョンを新たに指定します。
  2. メジャーアップグレードの場合、”jekyll-theme-chirpy” gemに含まれていない核心ファイルと設定オプションも変更されている可能性があります。この場合は以下のGitHub APIで変更点を確認した後、直接反映させる必要があります。
    1

      https://github.com/cotes2020/chirpy-starter/compare/<older_version>...<newer_version>
AI & Data, Blogging
Jekyll Markdown
This post is licensed under CC BY-NC 4.0 by the author.