Hugo — 静的サイトを高速生成

Markdown記法のテキストをHTMLに変換する、静的ウェブサイト生成プログラム。 公式ドキュメントが充実しているので基本的にそれに従えば簡単にできる。

• https://gohugo.io/documentation/
• https://github.com/gohugoio/hugo

高速さとシンプルさに惹かれてSphinxから移行し、 本サイトもHugoでビルドしている。 オフラインの研究ノートとしても有用。

Quick start

https://gohugo.io/getting-started/quick-start/

• Hugo本体をインストール。 方法はいろいろ用意されてる。

  • 手動でよければOSに合った公式prebuilt binaryをダウンロードしてPATHを通すのが簡単。
  • コマンドで管理するならHomebrewで一発: brew install hugo
  • ソースコードを改変したりしたい場合は git から:

    export GOPATH=${HOME}/.go
    export PATH=${PATH}:${GOPATH}/bin
    mkdir ${HOME}/src
    cd ${HOME}/src
    git clone https://github.com/gohugoio/hugo.git
    cd hugo
    go install -v
    

    SCSSのための --tags extended オプションは不要になった。

• SCSSを使う場合は Dart Sass を別途インストールしてPATHを通す。 この方法もいろいろあるけど 公式prebuilt binary を使うのが簡単。

  brew install heavywatal/tap/dart-sass
  # or
  wget -O- https://github.com/sass/dart-sass/releases/download/1.77.4/dart-sass-1.77.4-macos-x64.tar.gz | tar xz
  

• ちゃんとインストールできているか確認: hugo env

• 骨組みを作る:

  cd path/to/site
  hugo new site .
  

• ページをMarkdownで書く:

  hugo new about.md
  

  +++
  date = 2016-02-26T19:10:22+09:00
  title = "About"
  +++
  
  ## Heading
  
  normal *italic* **bold**
  

• テーマをとりあえず全部インストール:

  git clone --depth 1 --recursive https://github.com/gohugoio/hugoThemes.git themes
  

• 適当なテーマでウェブサーバーを走らせる:

  hugo server --theme blank
  

• ブラウザから http://localhost:1313/about にアクセスしてみる。 hugo server, hugo -w はファイルを監視していて変更をすぐに反映する。

設定

https://gohugo.io/getting-started/configuration/

長らく config.toml だったが今は hugo.toml がデフォルト。 config/_default/hugo.toml に置いても同じ。

config/ 直下のディレクトリ名と -e/--environment オプションで切り替え可能。 ただしデフォルトの挙動がわかりにくい罠なので注意。例えば config/_default/ と config/production/ を持って hugo を実行するとproduction環境になってしまう。 production環境を作らず config/public/ とかにしておけば明示的に -e public を渡さない限り常にデフォルトのdevelopment環境になるので分かりやすい。

hugo        # -e production (confusing!)
hugo -w     # -e development
hugo server # -e development

Theme

https://themes.gohugo.io/

デフォルトのテーマというものが存在しないのがちょっと厳しい。 ユーザーによっていろいろ投稿されてるけどほとんどがブログ用途。 ということで非ブログ用に簡単なものを自作して使っている:

https://github.com/heavywatal/hugo-theme-nonblog

Template

• https://gohugo.io/templates/
• https://gohugo.io/functions/
• https://gohugo.io/methods/

先頭のドット . は現在のcontextを表す。 普通のページのテンプレートではページを表す状態から始まり、 {{ with }} や {{ end }} などによって階層的に変化していく。

.Site.Params.author.name のように chain してメソッドや変数を参照できる。 TOMLやYAMLではハイフン - がキーに入っても問題ないが、 Hugo template では chain できなくなるため非推奨。 index 関数を使えばそういうやつでも参照できるけど。

{{ .Param "key" }}

.Params.key が存在すればそれ、しなければ site.Params.key を参照する。

{{ .Params.key }}: 各ページの front matter の [params] セクションに書いたものを参照。

{{ site.Params.key }} サイト全体の設定 hugo.toml の [params] セクションに書いたものを参照。

Performance

https://gohugo.io/troubleshooting/build-performance/

ページによって内容が変わらないテンプレートは partial の代わりに partialCached を使う。 ビルドするときに --templateMetrics --templateMetricsHints オプションを付けるとどのへんを変えたら良いか教えてくれる。

Content

Markdown

CommonMark

“Markdown"の正式な仕様というものが存在せず、 いくつかの方言(flavor)が乱立していたが、 現在ではこれが事実上の標準仕様となりつつある。 2017年からGFMがこれに準拠することになったのもよかった。

GitHub Flavored Markdown (GFM)

CommonMarkに準拠しつついくらかの機能を追加したもの。 基本的な書き方はGitHub Helpのページが読みやすい。

tables

task lists:

• - [ ]
• - [x]

~strikethrough~: ~text~, ~~text~~

extended autolink: < と > で挟まなくても https:// とか www. とかで始まるURLらしきものを認識してリンク生成する。

tagfilter: 生HTMLタグのうち悪用されやすいものを無効にする。 <title>, <textarea>, <style>, <xmp>, <iframe>, <noembed>, <noframes>, <script>, <plaintext>.

Goldmark

2019年末からHugoのデフォルトエンジン。

基本的にはCommonMark準拠だけど、 デフォルト設定での生HTMLコードの扱いがちょっと変。

Blackfriday

HugoのMarkdownエンジンは長らくこれだった。 CommonMark準拠じゃないし、 リストまわりでの不具合が放置されてるし、 などなど不満が募るうちにGoldmarkに取って代わられた。

Front matter

https://gohugo.io/content-management/front-matter/

タイトルや日付などのメタデータをファイルの先頭で記述する。 YAMLやJSONでもいいけど、 TOMLのほうが将来性ありそう。

閲覧・公開方法

Hugo Server

付属の簡易サーバーを起動。

hugo server
open http://localhost:1313/

localhost (Mac)

public/ 以下に生成されるファイルをシムリンクやコピーで /Library/WebServer/Documents/ に配置すれば http://localhost で閲覧できる。 ユーザーの ~/Sites/ をドキュメントルートにする方法でもいいが、 単にシムリンクを張るほうが楽ちん。

ls /Library/WebServer/
sudo mv /Library/WebServer/Documents /Library/WebServer/Documents.orig
sudo ln -s ~/path/to/public /Library/WebServer/Documents
open http://localhost/

5秒待たされる問題 を避けるため KeepAlive Off を設定しておく。 /etc/apache2/httpd.conf を直に書き換えるか、 /etc/apache2/other/keepalive.conf のようなファイルを作り、 sudo apachectl graceful で変更を反映。

GitHub Pages

public/ 以下に生成されるファイルをしかるべきrepository/branchに置くだけ。

See Git