用語
ビルド
成果物を出力する一連の作業です。
hugoのビルドは、静的リソース(html、css、画像、javascript等)を出力します。ビルドしたファイルをAmazonS3やGithubPagesにアップロードすると、そのまま表示する事ができます。
live reload
ライブリロード。htmlを保存するとブラウザがそれを自動検知し、記事の保存に反応してリアルタイムにブラウザを更新する事ができる機能です。markdownだけでなく、cssや画像の変更もlive reloadに反応して自動更新されます。
ただし、全く何も変更していない状態でエディタの保存を連打したりすると、変更が無いにも関わらずブラウザの自動リロードが実行されるので、あまり連打しない方がよさそうです。
draft
記事ファイルを生成した際に、.mdファイルの中身を見ると、以下のように記述されていますね。
+++
date = ""
draft = true
title = ""
+++
draftは「記事が編集中なのかどうか」を決めるフラグです。ビルドした際にdraftがtrueだとその記事はビルド対象にならず、成果物として出力されません。このdraftはレンタルブログで言うところの「下書き」です。記事が完成してwebに公開されてもいい状態になったら、draftをfalseに変更して保存します。
ただし、このままだとローカルで記事を書く際に、draft=trueにしてしまうと記事がpublicに出力されないため、404 not foudになってしまってローカルで画面表示ができなくなってしまいます。
この問題を解決するため、ローカルでhugoを起動する際は、「-D または –buildDrafts=true」オプションをつけます。このオプションはdraft=trueの記事もビルド対象に含める事ができるオプションです。これならまだローカルで書きかけの記事もlive reloadで画面を確認しながら記事を書く事ができるようになります。
この「-D」オプションですが、ローカルでのみ使います。CIサーバ等でビルドする際にこれを有効にしてしまうと、まだ下書き状態で公開したくないのにビルド対象になってしまって、下書き状態の記事がwebに公開されてしまうという事故が発生してしまうので、注意が必要です。
フォルダ構成
おおまかにHUGOのフォルダ構成は以下のようになっています。
project-root
├── archetypes
│ └── default.md
├── content
├── data
├── layouts
│ ├── index.html
│ ├── _default
│ │ └── single.html
│ └── partials
├── public
├── static
└── themes
/archetypes/
「hugo new xxx.md」コマンドで生成される記事ファイルの雛形です。
default.md というファイル名を配置すると使用されます。
/content/
記事の出力先フォルダです。「hugo new hoge.md」と実行すると、 /content/hoge.md が生成されます。
/data/
yaml、toml、json等の固定データを配置するフォルダです。
/layout/
htmlテンプレートフォルダです。
hugo起動時にテンプレートを指定しない場合、このlayoutフォルダが読み込まれます。
テンプレートを指定した場合、/layout/は読み込まれません。
/layout/index.html
サイトのトップページのhtmlです。
/layout/_default/single.html
記事詳細ページのhtmlです。
/layouts/partials/
例えばヘッダーなどのhtmlのパーツを配置するフォルダです。
html内で以下のように記述すると、/layouts/partials/header.html が読み込まれます。
{{ partial "header.html" . }}
/public/
成果物の出力先フォルダです。このフォルダに出力されたファイルが最終的なファイル群で、それらをS3やGithubPagesにアップロードしてデプロイします。
/static/
画像・css・javascript等の静的リソースを配置するフォルダです。
例えば /static/css/common.css を配置した場合、htmlでは以下のように読み込んで使用します。
<link rel="stylesheet" href="/css/common.css">
/themes/
hugoのテーマフォルダです。テーマはここに揃っています。
このページにも書かれていますが、プロジェクトのルートフォルダで以下のように再帰的にgit cloneすると、全テーマを一括ダウンロードする事ができます。(容量が大きいので注意)
git clone --recursive https://github.com/spf13/hugoThemes.git themes
テーマをcloneすると、「/themes/material-design-lite/layouts」といったフォルダ構造となります。このlayoutsフォルダはプロジェクト直下のlayoutsと全く同じ意味を持ちます。
テーマ
テーマには注意点があります。それは「全てのテーマが均一の機能を実装しているわけではない」点です。このテーマにはあの機能があるけど、あのテーマにはこの機能が無い、という事が普通にあります。
レンタルブログ等のテーマの場合は「必須要件・機能を満たしていないテーマは認めない」等の審査のようなものがあったりしますが、hugoにはそれがありません。それによって「このテーマにはタグ一覧表示機能がない!」「このテーマはページングの次へ・前へはあるけど、ページ番号リンクを生成してくれない!」といった、実装機能のバラつきが起きています。
現状残念ながら実装されている機能がバラバラなので、テーマを選ぶ際は見た目だけでなく「どの機能が実装されているか」という点にも着目して、デモサイトで事前に確認する事をおすすめします。
ライブリロードの有効範囲
hugoにはライブリロードが実装されていますが、「設定ファイル(config.toml, config.yaml)の変更はリロード対象外」な点に注意が必要です。
恐らくこの設定ファイルの更新をライブリロード対象に含めてしまうと、記事全体に影響を及ぼしてしまうので、リアルタイムにリロードするにはリロード対象が多すぎてリアルタイム化が難しくなる、といったパフォーマンス的な理由から、リロード対象外ないなっているのかもしれません。