Hugoで生成した静的サイトをGitHub Pagesで公開する

Windowsのパッケージ管理ツールとしてchocolateyをインストールします。
https://chocolatey.org/install

HugoやRubyをインストールする際に利用しました。

静的サイトジェネレーターとしてHugoをインストールします。
https://gohugo.io/getting-started/installing#windows

私自身、静的サイトジェネレーターの使用経験もなければ、HTMLやCSSも
ドットインストールでチュートリアルを実施したことがあるくらいで書けません。

そのため、どの静的サイトジェネレーターを使用するか悩みましたが、
参考記事にあげた"静的サイトジェネレーターの比較とHugoに決めた理由"を参考にして
他の静的サイトジェネレーターと比べても"爆速"というところに惹かれ、Hugoを採用した。

後はGoってなんか面白そうっていう単純な理由もあります😂

ブログ公開にあたってMustではないですが、Hugoで簡単かつ爆速に静的サイトを
生成できるというのが体験できるので実施しました。
https://gohugo.io/getting-started/quick-start/#step-2-create-a-new-site

※macOS向けの内容になっているので、コマンドはGit for Windows上で実施しました

GitHub Pagesは自前でサーバを用意せずに、GitHubのリポジトリから
直接Webサイトを公開できる静的なサイトホスティングサービスです。

リポジトリの推奨上限は1GBのようですが、ブログといった使用用途であれば
雑に計算して、1つの記事が10Kbだとしても200,000記事は書けるので
容量の大きい画像さえ載せなければスケーラビリティの問題はないでしょう。

もっとも、スケーラビリティを心配するほどブログの更新が続くかは怪しいですが😂

このタイミングではGitHub User Pagesとしてリポジトリを作成しました。
https://help.github.com/ja/github/working-with-github-pagescreating-a-github-pages-site

※後述しますが、最終的にはGitHub Project Pagesとしてブログを公開しています

GitHub Pagesのリポジトリに生成したWebサイト(以降、コンテンツ)を格納するだけ
https://gohugo.io/hosting-and-deployment/hosting-on-github#github-user-or-organization-pages

Youtubeにチュートリアルもありわかりやすかったです。
https://www.youtube.com/watch?list=PLLAZ4kZ9dFpOnyRlyS-liKL5ReHDcj4G3v=qtIqKaDlqXo

git-submoduleコマンドは初めて使ったが便利でした。
他にもworktreeなど便利なコマンドもあったので、ここらへんは後日まとめます。

テーマの一覧から自分が使いたいテーマを探して取り込みます。
https://themes.gohugo.io/

今回は見た目と色合いがシンプルで気に入ったのでErblogというテーマを使用することにしました。
https://themes.gohugo.io/erblog/

テーマの設定はconfig.tomlファイルに記述します。
今回はportraitなどテーマのREADMEを参考にカスタマイズしました。

※後々このテーマを選んだことで苦労したのですが、結果HugoのtemplateやHTMLの勉強にもなってよかったです。

Github User Pagesとしてコンテンツを公開していたため、
コンテンツ生成前のファイルやdeploy用のシェルスクリプトと
公開するコンテンツが別々のリポジトリで管理していました。

今回はブログに必要なファイルを1つのリポジトリでまとめて管理したかったので
blogというリポジトリを新規で作成し、GitHub Project Pagesの作法にならって
gh-pagesブランチからコンテンツを公開するように変更しました。
https://gohugo.io/hosting-and-deployment/hosting-on-github#deployment-of-project-pages-from-your-gh-pages-branch

gh-pagesブランチにはコンテンツを格納するpublicディレクトリのみをpushします。
ここらへんはgit-worktreeを使用することで1つのリポジトリに対して
複数のワークツリーを紐づけることができて、少ない手間で実行することができます。

これでHugoでブログのコンテンツを生成し、GitHub Pagesでインターネットに
公開することができました。👏

今のところmarkdownでも問題ないのだが、今後技術情報をまとめる上でUMLだったりを
掲載することもあると考え、Asciidoctorとdiagramのプラグインを入れおきました。
AsciidoctorはAsciidocファイルをHTMLファイルにコンバートしてくれます。
https://asciidoctor.org/

Hugoでは元々asciidocをサポートしています。
https://gohugo.io/content-management/formats/#external-helpers

なおパフォーマンスの関係からAsciidoctor呼び出し時のオプションに
「--no-header-footer --safe --trace」を指定しているようで
Asciidocの脚注といった表現を利用することができないようだ。

Recent Postsから投稿した記事へ飛ぼうとしたら404 Not Foundとなってしまいます…。
ブラウザのURLを見ると生成されたリンクが正しくありません。URLの設定周りがおかしそうです。
同様にCategoriesやtagsも正しいURLにリンクされていないことがわかりました。

結局、今回はerblogで使用しているPartial Templateを自前で用意したものに置き換える形で解決しました。

erblogで用意されていたPartial Templateのうち、いくつかファイルで
jsやcssファイルが正しくロードされていませんでした。

Partial Templates 上記を参考にlayouts/partials/配下に同名のhtmlファイルを用意します。
自前で用意したhtmlファイルでは正しくjsファイルがロードできるように
href属性を"{{.RelPermalink}}/jsファイルのpath"といった形式に書き換えます。
こうすることで正しくjsファイルの読み込みができ、レイアウトの崩れが発生するなど防ぐことができました。

HTMLで記述されたGo Templates内では"{{ }}"からHugoのvariablesやfunctionsを使用できます。
Basic Syntax 今後、自身でtemplatesをカスタマイズしたくなったらイジってみます。