Hugo を便利に使う小ワザ集

Hugo で日本語Webサイトを作成する際に、便利だと思った設定などをまとめてみました。

これらの設定はテーマを問わず使えるので、ぜひ試してみてください。

忙しい人のための設定完成形

[markup]
  [markup.goldmark]
    # 見出しに自動で ID を付与しない
    autoHeadingID = false

    [markup.goldmark.parser.attribute]
      # 要素にクラスや ID を付与する
      block = true

    [markup.goldmark.renderer]
      # マークダウン内の改行を改行として出力する
      hardWraps = true

      # マークダウン内で HTML を使用する
      unsafe = true

マークダウンファイルに直接 HTML を記述する

Hugo ではセキュリティのため、デフォルトではマークダウンファイルに直接 HTML タグを書くことはできません。

サイト側の hugo.toml ファイルに以下のように追加することで、HTML を直接書き込めるようになります。

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

これらの設定は、サイト側の設定ファイルに書かれていなければ反映されません。テーマ側に書いてあるからと油断せずに、サイト側のファイルに追記してください。

見出しに自動で ID が付与されないようにする

Hugo は自動で見出しに ID を追加してくれますが、日本語の見出しだと ID も日本語で登録されてしまいます。

## これは見出しです。

<h2 id="これは見出しです。">これは見出しです。</h2>

日本語の ID がだめだというわけではないのですが、気になる場合はこの機能をオフにすることができます。また、後述する方法で手動で好きな ID を付与することもできます。

[markup]
  [markup.goldmark]
    [markup.goldmark.parser]
      autoHeadingID = false

要素に任意のクラスや ID を付与する

記事を書いていると、「この段落は注意書きだから目立たせたい」と思うことがあります。そういったときに、この設定をしておくとclass="note" など好きな属性を追加することができるようになります。

[markup]
  [markup.goldmark]
    [markup.goldmark.parser]
      [markup.goldmark.parser.attribute]
        block = true

使い方は、要素の直後に {.class名} や {#ID名} を記述するだけです。

## これは重要な見出しです
{#important-title .important-title}

<h2 id="important-title" class="important-title">これは重要な見出しです</h2>

改行を改行として出力する

Hugo のデフォルトでは、段落中での改行は半角スペースをふたつ入れる必要があります。

ただの
改行（出力結果では改行されません）

行末に半角スペースをふたつ  
入れて改行（出力結果では <br> が挿入されます）

この仕様を知らないと「改行が反映されない」と苦しむことになります。知っていたとしても、うっかり忘れてしまうこともあります。

そんなときのために、この設定です。

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

これにより、段落中の改行でも <br> に置き換えて出力してくれるようになります。うっかりさんでも安心の設定です。

まとめ

Hugo はデフォルトでも使いやすいですが、環境やプロジェクトに合わせて自分で設定することでより使いやすくなります。こうしたカスタマイズも、Hugo の魅力のひとつですね。