はじめに

現在

markdownで書いた社内向け仕様書ドキュメントを、
GitHub+GitHubActions+Vuepress+S3でHTML化して共有しています。

静的サイトジェネレータの部分は何でもよかったのですが、
個人的にVue.jsがとっつきやすかったのでvuepressを選択してみていました。

しかし…

vuepressを使っているうちに課題を感じてきました。

• ビルド時間が長くなりすぎる
  • 最初は5分程度でしたが、最終的に10分近くかかっていました
• 最新コミットの内容をHTML側に出せない
  • これは頑張れば行けそうな気もしたけど…。

他にも諸々ありますが、とにかくビルド時間を早くしたい！というのが最も大きい課題感だったので、静的サイトジェネレータの中で圧倒的早さを誇るという「Hugo」に乗り換えてみることにしました。

実際にやってみた

やったこと

• Hugoのテーマ設定
• Hugobuild設定の変更
• markdownにfrontmatterを追加
• 記事ファイル名の変更
• 記事内に記載されているリンクの変更

ハマったポイント・違いを感じたポイント

README.md⇒_index.md

これはもしかして変えなくてもいけるのかもしれない…と思いつつ、
どう見ても_index.mdがデフォルトみたいだったので、
合わせてリネームしてあげました。

テーマをsubmoduleとして管理する方法にあまり慣れていなかった

配布されているdocsyをフォークして、
設定などをいじったテーマをプライベートリポジトリで管理して、
ドキュメントを管理しているリポジトリでサブモジュールとして追加した。

これはもう静的サイトジェネレータの問題ではないのだが、
個人的にgit submoduleに慣れていなかったのでややつまづいた。

サイドバーの構成方法があまり慣れていない手法だった

基本的に各記事内のfrontmatterのweightで指定する。

生成されるHTMLのURL形式がvuepressとは異なる

vuepressだとこうで

content/posts/_index.md
=> example.com/_index.html
content/posts/post-1.md
=> example.com/_post-1.html

Hugoだとこう

content/posts/_index.md
=> example.com/posts/
content/posts/post-1.md
=> example.com/posts/post-1/

s3のアクセス権限の与え方の都合上、example.com/posts/のようにサブディレクトリにアクセスするような形だとアクセスができない状態になっていたので困った。

URL Management
Hugo公式ドキュメントを見て、uglyurls=true設定にすることで対応できた。
そうするとこんなかんじになる。

.
└── content
    └── about
    |   └── _index.md  // <- https://example.com/about.html
    ├── posts
    |   ├── firstpost.md   // <- https://example.com/posts/firstpost.html
    |   ├── happy
    |   |   └── ness.md    // <- https://example.com/posts/happy/ness.html
    |   └── secondpost.md  // <- https://example.com/posts/secondpost.html
    └── quote
        ├── first.md       // <- https://example.com/quote/first.html
        └── second.md      // <- https://example.com/quote/second.html

（それでもvuepressの出力のされ方とは違うので、記事内のリンクを置換したりはしたけれど…）

コミットログを正しく表示するのに条件がある

コミットログがきちんととれているファイルとそうでないファイルが存在したが、何が違うのかすぐには分からなかった（特にWarnやErrorも吐かれていないし）。

調べてみたところ、ASCII文字のみで構成されているファイル名でないと、コミットログを正しく取得できないようだ。（つまり日本語ファイル名はNG）
元々は編集時の可読性を考えて日本語のファイル名にしていたので困った。

全部英語ファイル名にリネームしました。
(2021/5/12　追記)
以下を行うことで、日本語ファイル名のままでも問題なくコミットログが取得できることを確認できました！ @peaceiris さん、ありがとうございます。

git config core.quotePath false

cf. Non-ascii filename breaks lastmod · Issue #496 · peaceiris/actions-hugo

やってみた結果

少々手間はかかったけど、とにかくビルド時間が爆速になったので幸せです（約1分程度になりました。10分の1！）。

Hugoについてはさらに公式ドキュメントをよく読みこんで、
後日更に詳しいことも書いてみようと思います。
Hugoはけっこう更新頻度が高いようなので、楽しいですね。