Hugoを導入してブログを作った サイト構築編

Category: dev

Tag: blog Hugo

この記事はKobeUniv Advent Calendar 2015の17日の記事です。なんとか期日に間に合いそうです。 なお私は当該大学の学部1年(2015年12月現在)です。

このブログを作るにあたって、Hugoを使用しました。 Hugoを用いたサイト構築の基本的な考え方や流れの紹介、その際に詰まったことなど。

そもそもHugoって何

静的なWebサイトを生成するためのエンジンです。 つまり:

  1. まずレイアウトを用意します
  2. 次に記事を書きます
  3. hugoを実行します
  4. 記事がHTMLに変換され、Webサイトが生成されます
  5. 生成されたサイトをまるごとサーバーにアップロードします

これでWebサイトの完成というわけです。 あくまで静的なサイトなので、サーバーサイドでプログラムを走らせる必要もありません。

Hugoを使ってみる

Hugoのインストール等については、既に多くの情報がネット上にあるため割愛します。

Hugoの基本的なディレクトリ構成

$ hugo new site name_of_my_site

を実行することで、サイト用のディレクトリが生成されます。 中には、config.tomlといくつかのディレクトリが生成されているはずです。 config.tomlはサイト全体の設定を記述するファイルです。なお、代わりにconfig.yamlとしてYAMLで記述することなども可能です。お好みで変更しましょう。

$ cd name_of_my_site/
$ ls -p
archetypes/  config.toml  content/  data/  layouts/  static/

contentディレクトリは、記事ファイルを配置する場所です。

$ hugo new hoge.md

などとするとcontent内にmdファイル(記事は主にMarkdownで記述します)が生成されますので、これを編集して記事を作ることになります。

また、layoutディレクトリにはWebサイトの基礎となるテンプレートを配置します。 基本的には独自のテンプレート記法が用いられたhtmlファイルを使います。 既存のテーマを利用する場合は、themesディレクトリを作り、そこに同様のテンプレートが同梱されたテーマを配置することになります。

staticディレクトリには、CSSや画像などの静的なファイルを配置します。 このディレクトリ内にあるファイルは、生成時にサイトのルートディレクトリにそのままコピーされます。

基本的には、この3つ(または4つ)のディレクトリの働きを把握しておけば、Hugoでサイトを作りはじめるのに不足はないかと思われます。

また、hugoコマンドなどによって生成された完成品のサイトは、publicというディレクトリが作られてそこに配置されます。 サイトを公開するときは、publicディレクトリ下に生成されたファイルをすべてアップロードします。 なお、publicディレクトリ内に不要になったファイルがあったとしても、サイト生成時に削除されません。本番サイトの生成時にはpublicディレクトリを一度削除してからビルドを行うのが良いと思われます。

レイアウトしてみる

テーマを使う

いくつものHugoのレイアウトが公開されています。基本的には、この中から気に入ったものを使うのが良さそうです。themesディレクトリ直下にテーマごとのディレクトリを作り、その中にテーマファイルを配置します。

$ git clone --recursive https://github.com/spf13/hyde themes/hyde

テーマを適用するときは、configファイル内でテーマを指定するか、hugoコマンドの実行時にhugo -t hydeまたはhugo server -t hydeのように-tオプションでテーマを指定します。ここで指定するテーマ名は、themes直下に配置したディレクトリの名前となります。 テーマを適用すると、hugoディレクトリ直下のファイルが読み込まれるよりも先に、そのテーマディレクトリ下に存在するファイルが読み込まれるようになります。

既存のテーマを使用する場合、テーマによってconfigに記述する必要のある内容が大きく異なる可能性があります。READMEにどのような項目を記述すればいいかが書かれていると思いますので、必ず確認するのがいいでしょう。

自分でレイアウトする

HugoはGo言語のテンプレートエンジンを使用しており、各種パラメータを呼び出したり、部分ごとにHTMLファイルを分けて再利用することでサイトのレイアウトを記述していくことができます。

自分でHugoサイトをレイアウトする場合、確実に一定の学習コストが必要となるので、ここでは詳細には触れません。Hugoは公式ドキュメントが充実しているので、公式チュートリアルなどから始めるのがいいでしょう。また基本的なことであれば調べれば日本語の情報も得られると思います。

詰まったことなど

今回はHTMLやCSSを自分で書いてサイトを一つ作りたいと思っていたのと、自分以外のテーマ作者名の表記がページに現れるのが気に食わなかったので、このサイトでは既存のテーマを使用せず、自前でレイアウトを記述して構築しました。 その途中で、いくつか不具合に遭遇して詰まったりしました。

(バージョン0.14)配列の並び替えにバグがある

サイドバーに最近の投稿やタグ・カテゴリの一覧を表示させる際、たとえば.Reverseや.ByDateで並び替えを行うと、ページによって正常に並び替えが行われなかったり、ビルドするたびに並び順が変わる、低確率で配列の中身が重複して表示されたりします。 これは並び替えを行う関数が配列そのものに変更を加えているのが原因です。さらにビルド時に並列処理が行われることで処理順がビルドのたびに変化し得るため、同じ記述をしていてもページによって表示される内容が変わるといった不具合が発生したり、そのバグの再現性が低くなったりします。

このバグは開発版のバージョン0.15では修正済みであり、現行のバージョン0.14まででのみ発生します。

RSSUriオプションは使ってはいけない

Hugoではビルド時に自動的にRSSフィードも生成されますが、そのファイル名は常にindex.xmlとなります。

rssuri = "rss.xml"

のようにconfigファイル中に記述することで、RSSファイル名を変更する機能がありますが、この機能にはいくつもの欠陥があるため使ってはいけません。(2015年12月、バージョン0.14時点)

  • ルートディレクトリ直下のRSSファイルのファイル名はこの設定によって変更できるが、それ以外のRSSファイルはすべてindex.xmlのままになってしまう
  • .RSSlinkなどの変数を呼び出すと、間違ったリンクが返される
  • RSSファイル内のURLが間違ったものになる

Hugoを使ってみた感想

Hugoはシンプルで生成が非常に速いという評判があったため導入してみましたが、実際にサイトを構築してみると確かにそのような設計であることがよく感じられました。必要最小限の機能を持つように出来ており、簡潔なディレクトリ構造はとてもわかりやすいです。 生成速度についてはまだ記事数が少ないため何とも言えませんが、今のところは一瞬でビルドが完了するので良い感じだと思います。

とはいえ、レイアウトから自前で書き始めるといくつかの不満点が出てきます。 レイアウトに使用するテンプレートはHugoの全体の印象に反して煩雑です。そのため、Hugo特有のレイアウトの記述方法にある程度習熟しておくことは不可欠となります。 しかし、Hugoは公式ドキュメントが非常に豊富ではあるのですが、決して使いやすいというわけではないと思います。 全体を通して解説風のドキュメントとなっているために最初はわかりやすいのですが、それ故にリファレンスとしての機能を十分に果たしておらず、また別途APIリファレンスなどがあるわけでもないので、テンプレートなどの機能を調べるのがやや困難です。 (とはいえ、基本はGo言語のテンプレートエンジンを用いているらしいので、既にGoに慣れている方にとっては問題ないのかもしれません)

Hugoで使用するパラメータは、TaxonomyやPaginatorの概念が存在していることによってやや複雑な構造をしているため、ドキュメントの見通しが悪いのは問題になりがちだと思います。(rangeで.Data等で提供される配列の中身を回す時とTaxonomyを回すときの扱い方が微妙に異なるなど)

以上、Hugoを使ったサイト構築の紹介でした。 Hugoでサイトを作ってからWeb上にデプロイするまでも一苦労あったので、後日その流れについても書いてみたいと思っています。

あとページのデザイン難しいです。 CSS周りについても記事を書いてみたいですが、あまりに試行錯誤の連続なので何も書くことがないかもしれません……