本記事の概要
Hugoにおける記事の状態とビルドコマンドについて説明する初心者向けの記事です。
前提
Hugo+Blowfishテーマ適用済みの環境です。
なお、Windowsでの操作を想定しています。
(本記事が属するアドベントカレンダーについてもご確認ください)
Hugoにおける記事の状態について
Hugoにおける記事の状態としては、下記ののようになります。
大別すると、publishedか否かという形で2つの状態があります。
publishedではない場合は、その要因ごとに状態が割り振られています。
- published
- publishedではないもの
- drafts
- expired
- future
下記の公式サイトの記載も参考にすると良いです。
状態によって何が変わるのか？
publishedか否かによって、ビルドした際にpublicフォルダへ出力されるか否かが変わります。
即ち、Webサイトとして公開するか否かが決まります。
逆に言えば、記事を作成したのにもかかわらずページが出力されないのは、状態がpublishedではないのが原因です。
publishedとなる条件
先に記載した公式サイトにもありますが、下記のいずれの条件も満たさないものがpublishedとなります。
- publishedとならない条件(いずれかを満たせばpublishedにならない)
- draftがtrue(draftsとして扱われる)
- dateが未来(futureとして扱われる)
- publishDateが未来(futureとして扱われる)
- expiryDateが過去(expiredとして扱われる)
いきなり説明してもピンとこない人も多いと思うため、以降で詳細を解説します。
基本的なパラメーター(draft / date)
記事を公開するための最低限のパラメーターとして、draftとdateをまずは覚えておくと良いです。
- draft：記事が下書き(draft)状態か否か
- true：下書き(draft)状態である(publishedにならない)
- false：下書き状態ではない(publishedとなる可能性がある)
draftは、trueかfalseの状態を持ちます。trueであれば下書きのため、publishedになりません。
通常、記事を新規作成した際は、FrontMatterでtrueとなっている場合が多いです。
これは、書きかけの記事を誤ってWebに公開するのを防ぐためです。
したがって、一通り記事を作成したら、FrontMatterにあるdraftの値をtrueからfalseに必要があります。
- date：記事の作成日時を表します
- dateがビルド時の時刻よりも未来：未来の記事(future)状態(publishedにならない)
- dateがビルド時の時刻よりも過去：記事として存在(publishedとなる可能性がある)
dateは記事の作成日時を表します。
上記の通り、Hugoはビルド時の現在時刻とdateの時刻を比較します。
記事を作成した後ビルドするという流れですので、ビルド時刻よりdateの方が過去になるのが普通です。
したがって、その場合は記事として存在することになりますので、draftか否かによってpublishedか否かが決まります。
反対に、ビルド時刻よりdateの方が未来という場合、まだ作成されていない状態でビルドされていると判断できます。
そのため、futureとなり、publishedにはなりません。
ビルドを実行した時刻によってビルド結果が変わりうることに注意しましょう。
実際は各記事のFrontMatterで下記のように指定する場合が多いです。
+++
date = "2024-10-02T23:48:08+09:00"
draft = false
title = "記事名"
+++
最低限この２つさえ覚えれば、記事は公開できます。
作成から時間をおいてから公開したい(publishDate)
通常は、「記事をWebに公開したいから作成する」ので、作成が完了(draft=false)になった時点で公開しても何ら問題はありません。
しかしながら、少し高度な使い方としてこういったケースも考えられます。
- 2026年1月に発表したいコンテンツがある
- コンテンツ自体は、2025年中に作っておく必要がある為、先に作っておく
- つまり、作成してから2026年になるまでは公開してほしくない
上記の例は典型的な「情報解禁OKになってから公開したい」ケースになります。
このような場合に有効なのがpublishDateです。
publishDateに記事を公開してOKなタイミングを設定しておけば、そのタイミングになってからビルドすると、publishedとして公開されます。
publishDateになるまでは、futureとして扱われ、記事は公開されません。
+++
date = "2025-12-03T23:48:08+09:00" # 2025年中に記事は作成済み
publishDate = "2026-01-01T00:00:00+09:00" # 2026年になったら公開
draft = false # 作成済みなのでdraftはfalse
title = "記事名"
+++
publishDateは、cronなどのツールで定期的にビルド処理を回している場合に有用な方法です。
Pushの度にCIでビルドを回すといった場合は、実際に公開したいタイミングで再ビルドする必要があります。
ある時刻になったら公開を停止したい(expiryDate)
publishDateは作成から公開までに間がある場合の方法でしたが、反対にある時刻になったら公開を停止したいといった場合があります。
下記のようなケースを考えてみましょう。
- 2025年版、2026年版・・・といったように年ごとに別々の記事を作るとする
- 2025年版は、2026年になったら公開を停止する(expiryDateを使う)
- 2026年版は、2026年になったら公開を開始する(先のpuhlishDateを使えばよい)
このようなケースでは、expiryDateを使用すればよいです。
expiryDateで指定した時刻になってからビルドすると、publishedではないので、ビルドされなくなります。
+++
date = "2024-12-03T23:48:08+09:00" # 2024年12月に記事作成
publishDate = "2025-01-01T00:00:00+09:00" # 2025年になったら公開
expiryDate = "2025-12-31T23:59:59+09:00" # 2025年いっぱい公開(2026年になったら公開停止)
draft = false # 作成済みなのでdraftはfalse
title = "2025年版の記事"
+++
expiryDateも、cronなどのツールで定期的にビルド処理を回している場合に有用な方法です。
記事の状態の確認方法
PowerShell上でhugoコマンドを呼び出すことで、それぞれの状態に属する記事の一覧を取得できます。
hugo list (取得したいもの)といった形の構文です。
hugo list all # 全状態の記事の一覧
hugo list published # published状態の記事の一覧
hugo list drafts # drafts状態の記事の一覧
hugo list future # future状態の記事の一覧
hugo list expired # expired状態の記事の一覧
publishedではない記事をビルドしたい
デバッグや途中の状態の内容確認のために、publishedではない記事をビルドして確認することもできます。
hugoコマンドにオプションを足すことで実現できます。
hugo --buildDrafts # drafts状態をビルド対象に含む(-DでもOK)
hugo --buildFuture # Future状態をビルド対象に含む(-FでもOK)
hugo --buildExpired # Expired状態をビルド対象に含む(-EでもOK)
hugo serverコマンドも同様のオプションを受け付けます。
まとめ
Hugoの記事はpublishedか否かによって大きく分かれます。
それぞれの意味を理解することで、公開期間の対応が容易になります。
基本的にはデバッグや表示確認などを除き、publishedでは無いドキュメントをビルド対象に含めない方が安全です。
記事が表示されない場合は、コマンドなどでどの状態か確認してみましょう。