Weizlogy
作ったもの、気づいたこと、試したこと。元エンジニアの視点で技術をつづる雑多ブログ「Weizlogy」。
HugoからJekyll + GitHub Pages構成への移行記録と実務データ移行手順
静的サイトジェネレーターHugoで運用していたブログを、GitHub PagesネイティブサポートのJekyll構成へ移行した際の技術的背景、記事データの移行実務手順、およびトラブルシューティング結果を記録する。
概要・移行の背景
従来はHugoを利用してローカル環境で静的HTMLを生成し、生成物（public ディレクトリ）をリポジトリへプッシュする運用を行っていた。
- 課題: 記事更新ごとにローカルビルドと生成物のGit push手順が発生し、運用オーバーヘッドが大きかった。
- 解決策: MarkdownソースをGit pushするだけでGitHub側のRemote Theme / Jekyllエンジンにより自動デプロイが行われる Jekyll + GitHub Pages 構成へ移行した。
Hugo vs Jekyll 機能比較
| 項目 | Hugo | Jekyll + GitHub Pages |
|---|---|---|
| ビルド方式 | ローカル / CI等で手動・自動ビルドが必要 | Git pushのみでGitHub側が自動ビルド |
| ビルド速度 | 超爆速（Go言語製） | 標準的（Ruby製） |
| 運用の手間 | ビルド成果物（public）の管理が必要 |
Markdownとアセットのみの管理で完結 |
| テーマ管理 | Git submodule等で配置 | remote_theme 指定のみで完結 |
| 拡張性 | 非常に高いが学習コストあり | GitHub Pages標準プラグインが豊富 |
HugoからJekyllへのデータ移行実務
小規模ブログ（全20数記事程度）における現実的なデータ移行手順と、移行時のハマりポイントおよび対処法を述べる。
1. Front Matter（記事ヘッダー）の補正
HugoとJekyllでは記事冒頭のFront Matter仕様が異なる。
- Hugo: TOML形式（
+++）やYAML形式。draft: trueやtags等を使用。 - Jekyll: YAML形式（
---）が必須。また、レイアウトを指定するlayout: postの記述が必要となる。
日付フォーマットおよび layout: post の追加を一括または各記事の点検時に手動・スクリプト等で調整した。
2. 画像・静的アセットパスの変更（Grep & Replace）
Hugoでは static/img/... に配置した画像がルート /img/... として出力されるが、Jekyll（Minimalテーマ等）では assets/img/... 配下へ配置する構成をとる。
- 対処法: ディレクトリ構成を
/assets/img/へ変更し、全Markdownファイル内の画像リンク（）を、テキストエディタの Grep置換（一括検索置換） を用いて/assets/img/...へ書き換えた。記事数が限定的であったため、この力技アプローチにより迅速に変換が完了した。
3. URL構造（Permalink）の引き継ぎ
Hugo時代のURL構造とJekyllのデフォルトルーティング（/<category>/YYYY/MM/DD/title.html）を一致させるため、Grep置換による記事内リンクの修正とFront Matterの categories 整理を行った。
GitHub Pages & Minimalテーマで必須となる設定項目 (_config.yml)
GitHub Pages上でJekyllビルドを正しく機能させ、SEO（検索エンジン最適化）やテーマ適用を正常化するための必須設定を以下に示す。
1. _config.yml 必須設定サンプル
# 1. サイト・ドメイン基本定義（Sitemap・Canonical・OGP用）
title: Weizlogy
url: "https://blog.weizlogy.com"
baseurl: ""
lang: ja-JP
locale: ja_JP
# 2. Remote Theme 設定
remote_theme: pages-themes/[email protected]
# 3. 必須プラグインの指定
plugins:
- jekyll-remote-theme # Remote Theme（minimal）のロードに必要
- jekyll-sitemap # sitemap.xml の全自動生成
- jekyll-seo-tag # Canonicalタグ、meta description、OGP、JSON-LDの自動挿入
- jekyll-feed # RSS/Atomフィード（feed.xml）の生成
# 4. 抜粋区切り文字列
excerpt_separator: "<!--more-->"
# 5. 全ページのサイトマップ出力指定
defaults:
- scope:
path: ""
values:
sitemap: true
2. 各設定項目の役割と注意点
remote_theme:pages-themes/[email protected]を指定することで、ローカルにテーマファイルを保持することなくGitHub提供の公式Minimalテーマが適用される。plugins: - jekyll-seo-tag: 検索エンジンに正しい正規化URL（Canonical URL）やメタデータを伝えるために必須のプラグイン。Minimalテーマのheadタグ内で自動展開される。_includes/head-custom.html（独自拡張）: Minimalテーマでは_includes/head-custom.htmlを配置することで、Google Search Consoleの所有権確認用メタタグ（<meta name="google-site-verification" ...>）やアナリティクス解析タグを安全に追加できる。
ローカル開発環境とエラー対処
公式ドキュメント Jekyll を使用して GitHub Pages サイトを作成する を参考にローカル環境を構築した。
Windows環境における wdm Gem インストールエラー
Windows環境で bundle install を実行した際、ディレクトリ変更監視 Gem である wdm のビルドエラーが発生した。
An error occurred while installing wdm (0.1.1), and Bundler cannot continue.
原因と対処法:
wdm (Windows Directory Monitor) は必須依存関係ではないため、Gemfile から該当の参照行を削除またはコメントアウトすることで問題なくセットアップが完了する。
# Gemfile
# gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
Jekyllのファイル構造およびルーティング仕様
Jekyllにおける記事作成ルールとパーマリンクの挙動について整理する。
1. 記事ファイルの命名規則
_posts ディレクトリ以下に配置するMarkdownファイルは、以下の形式に従う必要がある。
YYYY-MM-DD-title.md
例: 2024-08-25-hugo-to-githubpages.md
2. URL（パーマリンク）生成規則
デフォルトのパーマリンク構成では、ファイル名の日付とタイトルに基づき以下のURLが割り当てられる。
- 基本規則:
/YYYY/MM/DD/title.html - Front matterで
categoriesを指定した場合:/<category>/YYYY/MM/DD/title.html
命名規則から外れたファイル名はビルド時に無視されるため注意を要する。