Post

GitHub Pagesブログの作成と管理

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

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

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

（+ 2024.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 （2021.01 〜 2022.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 （2022.04〜）

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

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

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

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

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

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

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

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

私は1番の方法を採用しました。Chirpyテーマの場合、基本的に完成度が高いため、ほとんどのユーザーの立場では大きくカスタマイズする必要がないうえ、2024年現在までかなり活発に開発および機能改善が進行中なので、よほど大幅な改造をするのでなければ、オリジナルのアップストリームをタイムリーに追従することのメリットが直接カスタマイズを適用することのメリットを上回ります。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. 配布する

2つの方法があります。

  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.