Hugo で blog サイトの作成: 環境構築編
構築手順の概要
前回の投稿 の方針に従って、下記の手順で準備する。
- Windows PC 執筆環境
- GitHub 連携
- サイト公開
Windows PC 執筆環境
事前準備
執筆環境として、Visual Studio Code をインストールしておく。 最近では winget コマンドを使うことで簡単にインストールできる。
winget install Microsoft.VisualStudioCodeHugo アプリのインストール
winget コマンドでインストール
winget install Hugo.Hugo.Extendedバージョンの確認
PS C:\> hugo version
hugo v0.135.0-f30603c47f5205e30ef83c70419f57d7eb7175ab+extended windows/amd64 BuildDate=2024-09-27T13:17:08Z VendorInfo=gohugoioHugo サイト (フォルダ) を作成
作業用フォルダに等に Hugo 用フォルダ構造を作成する。
mkdir "${env:USERPROFILE}\blog"
cd "${env:USERPROFILE}\blog"
hugo new site blog成功した場合は Congratulations! と表示される。
Congratulations! Your new Hugo site was created in C:\Users\XXXX\blog.
Just a few more steps...
1. Change the current directory to C:\Users\XXXX\blog.
2. Create or install a theme:
- Create a new theme with the command "hugo new theme <THEMENAME>"
- Or, install a theme from https://themes.gohugo.io/
3. Edit hugo.toml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>\<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".
See documentation at https://gohugo.io/.初期状態のフォルダ構造 (Hugo 0.135.0時点)
公式ドキュメント: Directory structure
blog/ # Hugoサイトトップフォルダ
|- archetypes/
|- assets/
|- content/ # 記事ファイル群の配置
|- data/
|- i18n/
|- layouts/
|- static/ # 静的ファイル (カスタムCSSや画像ファイル等)
|- themes/ # Hugoテーマ配置フォルダ
|- hugo.html # 設定ファイルビルド後に追加されるフォルダ
サイト公開する際は、ビルド後に public 以下のみを Web サーバにコピーすればよい。
blog/
|- public/ # Web公開用フォルダ Web
|- resources/git 初期設定
Hugo サイト全体を git 管理するため、初期化する。
cd "${env:USERPROFILE}\blog"
git initコミットしないフォルダを指定するため、同じフォルダに .gitignore ファイルを作成し、中身を以下の通り書いておく
/publicgit の初期設定も実行しておく。※ user変数は各自のものを入れる。
git config --global user.name "XXXXXXX"
git config --global user.email "[email protected]"
git config --global merge.ff "false"
git config --global push.default "simple"
git config --global pull.ff "only"初回の空コミットをしておく
git commit --allow-empty -m "first commit"Hugo テーマインストール
Hugo のテーマサイト からお好みのテーマを探し、Hugo サイトフォルダ配下に配置する。Git 管理にしたいので、下記のとおり subtree として展開する。
サンプルテーマの導入例
git remote add thenewdynamic-ananke https://github.com/theNewDynamic/gohugo-theme-ananke
git subtree add --prefix themes/ananke --squash thenewdynamic-ananke mastergit submodule でテーマを展開すると紹介している hugo 構築記事もあるが、場合によってはテーマ構造に手を入れる必要があるため git subtree の方が向いている。
Hugo 設定ファイル
初期設定例: hugo.toml
baseURL = 'https://example.org/'
title = 'New Hugo サイト'
languageCode = 'ja_jp' # 日本語対応
defaultContentLanguage = "ja" # 日本語対応
theme = "ananke" # テーマ名を指定
hasCJKLanguage = true # 日本語対応
[Params]
date_format = "2006/01/02(Mon)"Hugo設定ファイル補足
- Hugo 0.110.0 (2023/1/17) でデフォルト設定ファイル名が config.toml → hugo.toml に変更された
- Hugo 0.120.0 (2023/10/31) から [Author] タグが [Params.author] に変更された。この影響で不具合が出るテーマが存在するため、場合によってテーマファイル側の修正が必要。
記事を書く
基本的に content フォルダ以下に *.md ファイルを書いていけば認識されるのだが、特に固定されたファイル配置パターンはないらしい。
保守性を考えて、本 blog では下記の構造で構成することにした。
blog/
|- content/
|- posts/
|- YYYYMMDD-TOPIC1 # 記事1フォルダ
|- index.md # 記事1本体の MarkDown ファイル
|- xxxxx.jpg # 記事1に貼り付ける画像
|- xxxxx.png # 記事1に貼り付ける画像
|- YYYYMMDD-TOPIC2 # 記事2フォルダ
|- index.md # 記事2本体の MarkDown ファイル
|- xxxxx.jpg # 記事2に貼り付ける画像
|- xxxxx.png # 記事2に貼り付ける画像
|- privacy.md # サイト全体で固定の記事など- 記事ごとにフォルダをわけることで、記事から参照される関連画像とひとまとめにしておく
- フォルダ名に日付を入れることにより、記事の古い順にフォルダがソートされる
- URL にも日付が含まれるため、記事の古さが明確になる
- フォルダ名にトピック名を付記することで、URL 名だけでなんの記事か推測できるようにする
- 1階層のみのフォルダとし、管理をシンプルにする
- 記事をジャンル分けしたい場合は、タグ機能を利用する
記事フォルダを追加
記事を書き始める際は、hugo new で記事フォルダを構成する。
cd (BLOGトップフォルダ)
hugo new (記事フォルダ)/index.md実行例:
cd "${env:USERPROFILE}\blog"
hugo new posts/20240818-test/index.mdテンプレートに従ってひな形の index.md が自動作成される。
記事の執筆
index.md は下記の構造になっている。(TOML構造の場合)
---
+++
(Front Matterセクション)
title = '20240818 Test'
date = 2024-08-18T19:59:42+09:00
draft = true
...
+++
(本文)Front Matter セクションには記事ごとの固有情報を追記する。デフォルトは draft が true なので、下書き記事として認識され、public には配置されない。
本文は MarkDown 記法でエディタで記事を書いてゆく。
執筆用 PC で blog 表示テスト
hugo は簡易 Webサーバ機能を持っていて、下記のコマンドでプレビュー用に起動できる。
hugo -D server同じ PC からは表示された URL をブラウザで開くと、リアルタイムに変更が反映 される。
例) http://localhost:1313/
別の端末のブラウザから見せたいときは、下記のようにアドレス 0.0.0.0 (IPv4) か :: (Ipv6) でバインドする。
hugo -D server --bind ::GitHub 連携
筆者はあまり git を深く理解できていないので、以下の手順は不完全な可能性があります。
下記については別途準備しておく:
- Github の blog 用のアカウントで (プライベート) リポジトリ https://github.com/USERNAME/REPOSITORYNAME 作成
- Github アカウントに、blog 執筆 PC の ssh 公開鍵登録
GitHub リポジトリに commit + Push
git remote add origin https://github.com/USERNAME/REPOSITORYNAME.git
git pull origin master
git push origin master完了後、Github https://github.com/USERNAME/REPOSITORYNAME をブラウザを開いて、コードが登録されているか確認する。
サイト公開
Cloudflare とは
以前は Github + Netlify でサイト公開をしていたが、2024年9月に GitHub + Cloudflare Pages に移行した。主な理由は下記の通り。
- Cloudflare Pages は Free プランで CDN が利用でき、圧倒的高速化が図れる。
- Netlify は海外だったためか、ページ自体は軽いにもかかわらず、日本からの初回アクセスが若干遅かった印象。
- Netlify と Github の連携が若干分かりづらく、細かいエラーでデプロイが失敗することがあった。
- TLSサーバ証明書が無料 (Google Trust Service)
- HTTP/3 も対応
- Cloudflare Registrar に個人ドメインの DNS レジストラを委譲でき、原価で利用できる
- ムームードメインがここ数年毎年値上げしているため。(GMOに吸収されたせい？)
- Cloudflare DNS サービスで個人ドメインの公開 DNS ゾーンを登録でき、無料で利用できる。
- 以前は No-IP.com を使っていたが、ドル建て＋円安の影響で価格上昇していた。
- 今のところ Cloudflare DNS は「レジストラ費用は原価で提供」のコンセプトらしい。
Cloudflare に魂を売る ですべてを構成することで、ワンストップで blob 構築が可能になる。ただし、Cloudflare registrar は .jp 等の一部 TLD には対応していない ので注意。
参考: Cloudflare TLD ポリシー (対応TLD一覧)
Cloudflare Pages へのデプロイ設定
下記の設定をあらかじめ進めておく。Cloudflare Pages で公開するためには、最低限 DNS サーバホストを Cloudflare に移管しておく必要がある。
- Cloudflare アカウントの作成 (FreeプランでOK)
- Cloudflare DNS に自分のドメインのゾーンをコピーまたは登録
- Clounflare Registrar で、自分のドメインのレジストラを移管
- こちらは必須ではないが、価格的な理由で実施した。
Cloudflare Docs > Pages > Framework guides > Hugo | Deploy with Cloudflare Pages に従って、GitHub リポジトリとの連携設定を入れる。
これにより GitHub に Commit + Push すると、自動的に Cloudflare Pages がフックされ、hugo でビルドされ、サイトが公開される。
注意点として、デフォルトの Hugo バージョンが古いため、必ず変数 HUGOVERSION を執筆環境と合わせておくこと。設定を忘れると、執筆環境では表示されるにもかかわらず、Cloudflare Pages 側でビルドエラーが発生し、いつまで経ってもサイトが更新されないことがある。
サイト公開確認
GitHub → Cloudflare Pages ビルド連携が正常に完了すると、下記の一時 URLで確認することができる。
blog サイト正式公開設定
Cloudflare Pages で対象サイトに「カスタムドメイン」を追加することで、DNS にも反映される。
TLSサーバ証明書の割り当て等もよろしくやってくれる。反映には少し時間がかかるが、デプロイ完了後、正規な URL でアクセスできることを確認する。
以上
