2019/08/13

HugoとGitLab CIで手軽に素早くサイトを公開する

背景

少し前から、Markdown文書から静的サイトを生成したいという欲求がありました。主な理由は以下です。
  • ソースがテキストなのでdiff形式で簡単に差分を可視化できる。
    • 変更点を伝えなきゃいけない相手と共有しやすい。
  • 好きなエディタ（VSCode、Emacs、Vim etc…）で編集できる。
    • 作業効率が良くなる
静的ジェネレータと言えばGitHub PagesとJekyllが有名ですが、今回はHugoを使います。以下のキャッチコピーにしびれたのと、実際に使ってみるとキャッチコピー通り恐ろしく爆速だったからですヽ(=´▽`=)ﾉ
Install in seconds, build in milliseconds.
https://gohugo.io/

先人

実は社内の技術文書にこの技術を適用したいと考えていたので、以下の記事がとても参考になりました。
HUGOでMarkdownを使った技術ドキュメントの管理が良い
learn テーマ、素晴らしいですね。
  • 高速な全文検索が可能（日本語は難あり）
  • パンくずリストっぽいのがある
  • Edit this pageリンクも簡単につけられる
Hugoで生成したサイト内の検索については、公式の以下のページに詳しく記述があります。
Search for your Hugo Website
learnテーマはlunr.jsを使ってるようで、英語での検索は高速かつ良い感じなのですが、日本語検索はインクリメンタルサーチがうまくいきませんでした。
日本語検索については、ビルド時にインデックスのJSONファイルをを作って純粋にJSONをフロントエンドで検索する方法などが多く実践されているようです。むしろPublicなサイトならGoogleのサイト内検索に任せるのが良いのかぁ〜と思うのですが、この記事では解決策の実践には至っておりません。すみません(´・ω・｀)

テーマ設定

テーマのインストールにgit submodule addを使います。私のように、このコマンドにあまり馴染みがない方は以下の記事も参照してください。
Git submodule の基礎
コードのシンタックスハイライトのための書き方は、以下が参考になります。
Syntax Highlighting

GitLabによるCI/CD

この記事ではCI/CD基盤にgitlab.comを使います。
以下を読みながら.gitlab-ci.yamlを作ってGitLabのパイプラインが動作するようにします。
Host on GitLab
config.tomlのbaseURLを修正します。変更点の詳細はこちら。
GitLab公式のリポジトリに、Hugoを使った静的サイト生成のためのサンプルがあります。これも凄く参考になるのでオススメです。
hugo

つくったもの

こんな感じになりました！ʕ◔ϖ◔ʔ
Hugo良いですね。好きになりました(* ´ω｀ * )
また、図らずも検索機能と面と向き合うきっかけになりました。今回は私のスキル不足で完全敗北でしたが、これについてはもう少し勉強して出直したいと思います。
at
Labels: , ,