【Hugo設定】hugo.toml (config.toml) の基本と便利な設定項目

Hugoで構築したWebサイトのタイトルを変更したり、1ページあたりの記事表示件数を変えたり、Markdownの変換ルールを独自に調整したい時に編集するのが、プロジェクト直下にある hugo.toml（旧名: config.toml） という重要な設定ファイルです。

この記事では、チュートリアルで実際に使用している設定部分を中心に、hugo.toml に記述できる便利な設定項目の中身を初心者向けに解説します！

1. 基本設定 (Global Configuration)

サイト全体に関わる設定です。

baseURL = 'https://example.com/'  # サイトのURL (必ず最後にスラッシュをつける)
languageCode = 'ja'               # 言語コード
title = 'My Hugo Blog'            # サイトのタイトル
theme = 'my-theme'                # 使用するテーマ名

paginate = 10                     # 1ページあたりの記事数

# サイト独自のパラメータ (テンプレート変数 .Site.Params で呼び出せる)
[params]
  description = "サイトの説明文"
  ogp_image = "images/ogp.png"    # デフォルトOGP画像

baseURL: サイトのURLです。本番公開する時はここを https://example.com/ のように書き換えます。
languageCode: サイトの言語です。日本語なら ja にします。
title: ブラウザのタブや検索結果に表示される、サイトのタイトルです。
theme: 使用するテーマのフォルダ名 (themes/ 以下のフォルダ名) を指定します。
- ※安心ポイント: ここで指定したフォルダ名が、公開サイトのURLなどにそのまま表示されることは基本的にありません。フォルダ名が外部にバレる心配はしなくて大丈夫です！
- もしバレたら？: 基本的に セキュリティ上の問題はありません 。ただし、「社外秘のプロジェクトコードネーム」などをフォルダ名にしている場合は、名前からプロジェクトの存在が推測される可能性はゼロではありません。一般的なブログやサイトであれば、全く気にする必要はありません。

2. Markdownの設定（Renderer）

Markdownの変換ルールを細かく設定できます。
このチュートリアルでは、書きやすさを重視して以下の設定を追加することをおすすめします。

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true
      hardWraps = true

※ [markup.goldmark] とは？
これは、Hugoが現在標準で採用しているMarkdown変換エンジン 「Goldmark」 の設定だよ、という意味です。
最近のHugoではデフォルトでこのGoldmarkが使われており、高速で高機能なのが特徴です（Render Hooksなどの新機能も、このGoldmarkエンジンだからこそ動いています）。

`unsafe = true`

「HTMLタグの使用を許可する」 設定です。

Hugoの標準仕様では、セキュリティのためMarkdownの中に書いた <div> などのHTMLタグは無視されます。
これを true にすることで、記事内で自由にHTMLタグが使えるようになります（YouTubeの埋め込みコードなどを貼る時に便利！）。

`hardWraps = true`

「改行をそのまま表示する」 設定です。

Markdownの標準仕様では、改行はスペース扱い（つながって表示）になります。
日本語の文章では不便なので、これを true にして、エディタでの改行がそのままWeb上の改行（<br>）になるようにしています。

よく使われるその他の設定

他にも、こんな設定が便利です。

目次（Table of Contents）の設定

記事の見出しから自動で目次を作成する機能の設定です。
表示ルール（どの見出しレベルまで含めるかなど）を変えたい場合に使います。

[markup.tableOfContents]
  endLevel = 3      # h3までを目次に含める
  ordered = false   # 番号付きリストにしない
  startLevel = 2    # h2から目次を作る

目次の表示・設定方法を詳しく知りたい方はこちら：【Tips】目次（TOC）を自動生成する方法

コードハイライト（Highlight）の設定

記事内のプログラムコードの色分け設定です。

[markup.highlight]
  noClasses = false  # CSSクラスを使って色指定する場合
  style = 'monokai'   # 配色のテーマ（noClasses=trueの場合のみ有効）

その他のスタイルや設定はこちら：【Tips】コードブロックを綺麗に見せる（シンタックスハイライト）

3. 独自の変数を定義する (params)

Hugoの設定項目だけでなく、「自分だけのオリジナル変数」 を作って、サイト全体で使い回すことができます。

[params]
  copyright = "My Blog Inc."  # フッターのコピーライト
  postLimit = 10              # 記事の表示件数
  themeColor = "#ff0000"      # テーマカラー

このように [params] というグループの下に書いた値は、テンプレートファイルからいつでも呼び出せます。

テンプレートでの使い方: {{ site.Params.copyright }}

電話番号や住所、SNSのURLなど、「色々な場所で使うけど、変わるかもしれない値」はここにまとめておくと、後で直すのが楽になりますよ！

Q. 「TOML」って何？

このファイルの書き方（フォーマット）の名前です。
「トムル」 と読みます。

キー = 値 の形で書く。
[カテゴリー] でグループ分けできる。

という、人間にも読みやすいシンプルな形式が特徴です。
もし hugo.yaml や hugo.json というファイルを見かけても、書式が違うだけで役割は同じです（Hugoはどれでも読めます）。

書式の比較

同じ内容を3つの形式で書き比べてみましょう。

TOML (hugo.toml)

baseURL = 'http://example.org/'
title = 'My Site'
[params]
  author = 'Me'

YAML (hugo.yaml)

baseURL: http://example.org/
title: My Site
params:
  author: Me

※ キー: 値 の形式。インデント（字下げ）で階層を表します。

JSON (hugo.json)

{
  "baseURL": "http://example.org/",
  "title": "My Site",
  "params": {
    "author": "Me"
  }
}

※ カッコ {} とダブルクォーテーション "" が必須で、少し記述が厳格です。

hugo.tomlを編集して自分好みのサイト環境に整えよう

hugo.toml の役割を知れば、サイトの基本情報からMarkdownの細かな挙動（HTML描画の許可など）、さらには独自のカスタムパラメータの作成まで、全体に関わる設定を一元管理できるようになります。TOML、YAML、JSONなど、あなたが扱いやすいファイル形式に合わせて設定ファイルと上手に付き合っていきましょう！🛠️