Hugoで記事を書くにあたって利用している便利な仕様や機能等を紹介します。
新しい情報があれば随時追加します。

画像を記事ごとのフォルダにまとめる

このサイトでは、記事ごとに index.md と画像をまとめる Page Bundle を使っています。記事を移動するときに画像も一緒に扱えるのが便利です。

content/
└── program/
    └── example/
        ├── index.md
        └── images/
            └── hoge.png
static/
└── images/
    └── Author.png

index.md から記事用画像を表示する場合は、次のように書きます。リンク先を囲むのは丸括弧です。

![画像の説明](images/hoge.png)

サイト全体で使う画像は static/images/ に置き、ルートからのパスで参照します。

![プロフィール画像](/images/Author.png)

上のファイル名は説明用の例です。自分の記事に置いた実際のファイル名に合わせてください。 詳しくはHugoのPage Bundles を参照してください。

config.tomlをローカルテストとパブリッシュ用で切り替える

hugo serverを使用したときと、hugoを使用したときで参照するconfig.tomlを切り替える事ができます。
やり方はディレクトリ構成を

• Hugo_example
  • config
    • development
      • config.toml
    • production
      • config.toml

とするだけ。
hugo serverの時はdevelopment配下にあるconfig.tomlが読み込まれ、
hugoの時はproduction配下にあるconfig.tomlが読み込まれます。

僕の場合、developmentではサイトタイトルを「ローカルテスト」とし、GoogleAnalyticsを無効化しています。

詳細はこちらのHugoドキュメントへ

アコーディオンの実装

Shortcodeでアコーディオン機能を実装しています。

こちら で解説

プレビューしながら記事やThemeの編集

hugo serverでローカルサーバーを立ち上げた状態で、各記事のMarkdownやThemeのカスタマイズを行うと即座に反映されます。
記事Markdownは最終出力を見ながら編集できるのでやりやすいです。

また、僕は記事を書きながら改善点を見つけた時にcustom.cssを弄ったりしていました。

Themeのカスタマイズする際、htmlを見たこともありませんでしたが、触った所がリアルタイムでプレビューされるので「大体ここっぽい」から書いては消してを繰り返して徐々に理想へと近付けていけました。

サイトをLightHouseで評価

LightHouseとは、Webサイトのパフォーマンスを評価してくれるツールです。
ブラウザ上でF12を押すと出てくる開発者用コンソールの中にあります。

サイトの改善点を出してくれます。

例えば僕は画像ファイルがデカすぎるって言われたので改善しました。

ここで出されるスコアは環境に左右され、個々で導入している拡張機能も判定に含まれたりします。
参考程度に留めておくのがいいかもしれません。

フォルダ･ファイルの命名規則は作っておく

フォルダの大文字･小文字の違いでファイルが参照されなくなる事がありました。

画像ファイルにてhugo serverで確認すると正常だけども、パブリッシュされたサイトには表示されない事がありました。
原因は実際のフォルダ名称と、参照パス内で大文字･小文字の食い違いが起こっていたからでした。
おそらく誰もが一度は経験するような事だと思いますが‥‥備忘録として。

自分の場合は全て小文字にするようにしました。

AI対話サービス

2025/02/19追加

ChatGPTやCopilotなど、AI対話サービスは記事を書く上で非常に便利です。
一度書ききった後の誤字チェックや、見出し・文章の整理に使えます。手順や数値、リンク先まで正しいとは限らないので、生成された文章は公式資料や実際の動作と照らし合わせてから載せる必要があります。

様々な使い方ができ、無料サービスも多々あります。便利なものはどんどん利用しましょう。

また、VScode上のCopilotが非常に便利です。
mdファイルを食わせて「ですます口調に変えて」というだけで変換してくれます。
変更箇所はハイライトされ、1箇所ずつ確認しながら承認･破棄を選べます。ただし、文体の変更でも意味が変わることがあるので、差分の確認は必要です。

一部記事を一覧から除外(build.list)

2025/02/21追加

指定記事をホームの記事一覧に表示されないようにできます。
latests等からも表示されなくなります。

記事のフロントマターに下記のハイライト部分を追記するだけです。

1
2
3
4

---
title: "タイトル"
build: { list: never }
---

このサイトでは免責事項 とプライバシーポリシー を非表示にしています。

更新履歴

• 2026/09/08
  • Page Bundleと画像記法、リンク先、現在のbuild.list記法を修正
  • AIによる編集内容を確認する際の注意を追記
• 2025/02/19
  • AI対話サービスについて追記
• 2025/02/21
  • _build.listについて追記

関連記事

Hugoのテーマカスタマイズ（Robust）

参考記事

Memorandom : Hugoで記事毎に画像ファイルを管理する
Qiita Progrhyme : Hugoで環境によって設定を変える方法
まくまくHugoノート : Hugoでページリスト（記事一覧）に列挙されないページを作る (_build.list)