HugoとGithub Pagesでこのサイトができるまで

先人たちの積み上げた記録がすでにあるので、今更わたしが書いてもオリジナリティは限りなくありませんが、備忘録として書いておきます。
間違えて認識している部分が大なり小なりあると思うので、鵜呑みにしないでください。

インストール手順について、 Installation｜Hugo に環境に合わせた手順が乗っています。
また、Github Pagesだけでなく、なんらかのサービスを利用してWEB上に公開する方法も Host and deploy｜Hugo にあります。

公式のドキュメントを参照するのが一番いいです。

それはさておき、ここではWindowsでHugoを利用する場合について説明していきます。

概略

1. 必要なツールを用意する
2. Githubにリポジトリを作る
3. リポジトリのGithub Pages項目を設定する
4. 初期状態のサイトを作成する
5. Github Workflowsを設定する
6. テーマを導入する
7. 設定ファイルを編集する
8. ローカルで記事を書く
9. ローカルサーバーで表示チェックをする
10. commitをGithubにpushする

1. 必要なツールを用意する

Hugo｜Github より、環境に合わせたものをダウンロード、好きな場所(たとえばD:\Hugo)に展開してください。
PATHを通しておくと便利です。
テーマによってはExtendedエディションを要求されるので、どれをダウンロードしたらよいかわからない場合はhugo_extended_<version>_windows-amd64.zipを選べば問題ないと思います。
エディションの違いは Frequently asked questions｜Hugo を参照してください。

Github にログインできるようにします。

Git for Windows より、ファイルをダウンロード、インストールしておきます。

エディターとして、vscodeがあれば便利かもしれません。お好みで。

2. Githubにリポジトリを作る

Github上に好きな名前(たとえばhugo-blog)でリポジトリを作成してください。
この名前は、https://<user-name>.github.io/<repository-name>/のように、Github Pages上のURLに使われます。

なお、通常、リポジトリのvisibilityはpublicで全世界に向けて公開されています。設定をprivateにしてリポジトリを非公開にすることもできますが、その場合、無料ユーザーはprivateなリポジトリをGithub Pagesに使うことはできません。

GitHub Pages サイトを作成する｜Githubドキュメント

リポジトリを所有しているアカウントが GitHub Free または Organization 用の GitHub Free を使用している場合、そのリポジトリはパブリックである必要があります。

次に、作成したリポジトリから、gitのcloneコマンドを使いローカルリポジトリ(たとえばD:\project\hugo-blog)を作成します。
vscodeの場合はGitリポジトリのクローン項目から実行できます。

3. リポジトリのGithub Pages項目を設定する

リポジトリのSettingsページからPagesを開き、Build and deploymentの項目にあるSourceをGithub Actionsにしてください。
この設定で、後述する Github Workflowsを設定する の出力結果がGithub Pagesに渡されるようになります。

4. 初期状態のサイトを作成する

ローカルリポジトリの一つ上の階層をターミナルから開いてください。たとえばD:\project\hugo-blogがローカルリポジトリならば、D:\projectです。
hugo new site <リポジトリ名> --forceを実行することで、リポジトリフォルダにサイトを構成するファイル群が作成されます。
--forceをつけているのは、すでにリモートからクローンしたリポジトリフォルダがあるためです。
リポジトリ名がhugo-blogならば、hugo new site hugo-blog --forceとなります。

先にローカルでフォルダを作成しておく場合は、hugo new site <リポジトリ名>後に<リポジトリ名>フォルダに移動し、git initコマンドを実行しておきます。

次に、<リポジトリ名>\.gitignoreファイルを作成し、テキストエディタで/public/と記述してください。
これは<リポジトリ名>\public\フォルダをgitの管理から除外する、という意味です。

publicフォルダはhugo buildやhugo serverコマンドを実行した際に自動で作られるもので、サイトを構築する実際のファイル群が収められています。
次項で設定するGithub Workflowsを利用する場合は、GitHub側(リモート側)でpublicフォルダを生成するため、ローカルのpublicフォルダをpushしてはいけません。そこで、git管理から除外しています。

5. Github Workflowsを設定する

詳しくは公式のドキュメントを参照してください。
Host on GitHub Pages｜Hugo

まず、<リポジトリ名>\.github\workflows\hugo.yamlを作成します。
このファイルは「リポジトリにpushがあった場合、Github側のマシンでhugoを動かし、リポジトリからサイト用ファイルをビルドし、生成されたサイトをGithub Pagesで公開する」という作業の自動化を設定するためのもの。

ファイルの内容は、先程の Host on GitHub Pages｜Hugo より、ProcedureのStep4に書いてあるhugo.yamlをコピペしてください。
わたしは一部改変して、公式ドキュメントではTZ: Europe/Osloとなっている部分を、TZ: Asia/Tokyoとして利用しています。

6. テーマを導入する

このままではサイトを構築するためのファイルが不足しているので、手軽に問題を解決するためにテーマを導入します。
Hugo Themes より、好きなテーマ選び、そのドキュメントに示されているインストール手順に沿って導入してください。
多くのテーマがGithub上で公開されており、git submodule addコマンドを使って導入することを推奨していると思います。
後々の管理のためにも、必ずそれに倣って導入してください。

また、テーマを適用するには必ず設定ファイルであるhugo.tomlを編集する必要があります。

7. 設定ファイルを編集する

設定ファイルの位置は<リポジトリ名>\hugo.tomlです。中身はテキストなので、メモ帳などのテキストエディタで開くことができます。
設定項目の詳細については、 Configuration｜Hugo を参照してください。

前段で導入したテーマのドキュメントに従って設定ファイルへ追記します。
記述内容はテーマによって異なるため、テーマのドキュメントをよく確認してください。

一例として、hugo-bearblogテーマを利用した際のhugo.tomlについては、hugo-bearblog/exampleSite/hugo.toml｜Github に例示されています。

また、Github Pages用に次の内容も追記しておきます。(詳しい解説は Host on GitHub Pages｜Hugo 参照)

1[caches]
2    [caches.images]
3        dir = ':cacheDir/images'

注意点として、[]で囲まれたヘッダー行から始まる一連のブロックはテーブルと呼ばれ、トップレベルのkey = value形式よりも下の行に配置する必要があります。
TOML: 日本語 v1.0.0 #テーブル によると、こうあります。

テーブル (ハッシュテーブルや辞書とも呼ばれる) は、キーと値のペアの集まりです。 これらはヘッダーによって定義され、行に角括弧が単独で配置されます
(略)
その下、次のヘッダーまたは EOF までが、そのテーブルのキーと値のペアです。

たとえば、以下の記述は問題ありません。

1# よい例
2title = "Test Site"
3theme = "wonderful-theme"
4
5[caches]
6    [caches.images]
7        dir = ':cacheDir/images'

しかし次のようにすると、titleやthemeは[caches.images]のテーブルに乗ってしまい、Hugoは正しく動作しません。

1# 駄目な例
2[caches]
3    [caches.images]
4        dir = ':cacheDir/images'
5
6title = "Test Site"
7theme = "wonderful-theme"

8. ローカルで記事を書く

これで準備は完了しました（そのはずです）。
早速記事を書いていきます。

記事はhugo new <post>で作成できます。

例として、hugo new hello-world.mdコマンドを実行してください。hello-world.mdが<リポジトリ名>\content\に出力されるはずです。
基本的に、こうやって記事を編集していくことになります。

出力されたばかりのファイル内容はテーマによって微妙に異なるため、最低限の例を示しておきます。

1+++
2date = 'YYYY-MM-DDThh:mm:ss+09:00'
3title = 'hello-world'
4draft = true
5+++

この+++で囲まれた空間はページのフロントマターと呼ばれるメタデータ群で、たとえばdateは記事の作成日時を示しています。
通常、記事へのURLは、たとえばhttps://<user-name>.github.io/<repository-name>/hello-worldという具合に、作成したmdのファイル名でアクセスすることになります。メタデータのtitleは表示用で、基本的にURLには影響しません。
draftはファイルが下書き中か否かを示すためのものです。trueならば下書き中、falseならば脱稿済み、ということになります。
draft = trueの記事は、hugo buildやhugo server実行時に構築されるサイトには取り込まれません。ただし、リポジトリ上にmdファイルとしては存在するので、たとえばGithub上のリモートリポジトリならば誰からも閲覧可能です。
また、テスト用のローカルサーバーの場合は、コマンドラインに引数を加えることで、下書き中のものも表示することができます。(後述)

本文は+++で囲まれたフロントマターより下の行にマークダウン記法で書いていきます。

1+++
2date = 'YYYY-MM-DDThh:mm:ss+09:00'
3title = 'hello-world'
4draft = true
5+++
6
7Hello World !

9. ローカルサーバーで表示チェックをする

hugo serverを実行しローカルサーバーを起動させ、表示されるURLをブラウザで開き確認してください。
初期状態であれば、http://localhost:1313/がURLになっているはずです。

draft = trueのページも表示したい場合は、hugo server -Dを実行することで下書き中の記事も表示できます。

モバイル機器からの表示を確認したい場合は、ブラウザのウェブ開発ツールを開き、デバイス エミュレーション(ブラウザによって名称は異なる)を切り替えることで表示の確認ができます。

ローカルサーバー起動中はファイルの更新を自動で反映されます。

ファイルを変更したにも関わらずローカルサーバーに反映されない場合は、一度ローカルサーバーをctrl + cコマンドで終了させ、publicフォルダを削除後、改めてサーバーを起動してみてください。

10. commitをGithubにpushする

問題がないことを確認したら、draft = falseへと書き換えてcommitし、pushでリモートリポジトリに変更を反映させてください。

push受けて、Github Workflowsを設定する で設定したActionsが自動で走り、数分とかからずサイトが作成されるはずです。

サイトにアクセスして問題がないことを確認したら、以降は 8 - 10 の繰り返しとなります。

以上、基本的な流れでした。

ここまで書いてきてなんですが、初めて試す場合はいきなりGithubとの連携はせず、まずはローカルで試して使用感を確認してからGitやGithubを触ってみるといいかもしれません。

特にテーマに関して、多くのテーマがデモサイトを公開しているものの、読み手として見た時と実際に作り手として触った時の印象は違います。
試してみたい複数のテーマをthemesフォルダに配置して、hugo.tomlを編集しつつ自分のサイト構造・記事を使って比較してみることをおすすめします。

Hugoの重要な要素である分類方法について、わたしなりの理解を書いておきます。
詳しくは Sections｜Hugo や Taxonomies｜Hugo を参照してください。

大雑把に言えば、フォルダ構成による分類をセクションと呼び、フロントマターにtags = ["Hugo", "Github"]などと記述していく分類をタクソノミーと呼んでいるようです。

セクションは物理的構造に縛られており、また、URLに直結するため、縦軸の分類といえます。
セクション毎に表示方法を調整でき、このサイトで言えば「禍話リライト 」と「ブログ 」はまったく別物として表示されています。

一方で、属性や性質を論理的に分類したものがタクソノミーで、横軸の分類といえるのではないでしょうか。
公式ドキュメントを見てもわかるように、タクソノミーはサイト作成者がその用途に応じて自由に設定できます。
たとえば小説を紹介するサイトなら、分類方法はtags一つではなく、他にもauthor(s)、genres、publisherなどが考えられますね。場合によってはseriesも必要かもしれません。
一方で、テーマによってはタクソノミーの利用に縛りがあります。
柔軟にタクソノミーを利用したい場合は、最終的にテーマを自作していくことになりそうです。

Hugoは Content adapters という機能を持っており、これを利用することでヘッドレスCMSの記事データを扱えるようになります。
ただし、そうする場合、Content adaptersで利用するファイル内にサービスのAPIやそれを利用するためのKEYを書かなければならないので、今回記したGithub上にリポジトリを作成する手法そのままではセキュリティ上の問題があります。

たとえContent adapteesを利用しなくても、Github上のリポジトリは設定でprivateにしない限り誰でも閲覧可能、ということは常に念頭に置いておきましょう。