はじめに

「なぜ思い通りに改行されないのか？」
初めてHugoを使ったとき、私はこの疑問に頭を悩ませた。
Markdownで記述しているにもかかわらず、ブラウザで表示すると文章が勝手につながってしまう。見出しも段落もすべてが一塊に表示されてしまう。これは一体何が起きているのか？

結論から言えば、HugoのMarkdownパーサーには独自の仕様がある。それを知らなければ、どれだけMarkdownを正確に書いても、表示は思い通りにならない。

この記事では、HugoでMarkdownの改行とHTMLタグを正しく扱うための設定方法と注意点を、実体験と共に解説する。

Contents

Hugo特有の改行ルールに潜む罠

Hugoが採用するデフォルトのMarkdownパーサーは「Goldmark」だ。
このGoldmarkは、驚くほど厳密に公式Markdown仕様に従う。
そのおかげで一貫性は高いが、反面、扱いにはちょっとした“クセ”がある。

Goldmarkでは、行末に半角スペースを2つ入れることで初めて改行と認識される。普通に文章を書いても、行を変えただけでは改行されない。つまり、こういうことだ：

これは改行されません。
次の行も同じ段落として処理されます。

私は最初、この仕様に気づかず、「テーマの不具合か？」と無駄な調査を繰り返していた。
その後、設定ファイルに手を加えることで、問題はあっけなく解決した。

プロジェクトのルートにあるconfig.yamlを以下のように設定するだけで、Markdownの挙動が一変する。

markup:
  goldmark:
    renderer:
      unsafe: true
    parser:
      hardLineBreak: true

renderer.unsafe: true
HTMLタグ（たとえば <br> や <div>）をMarkdownの中でも使えるようになる。この設定を入れておかないと、HTMLが勝手に“除去”されてしまうことがある。
parser.hardLineBreak: true
通常、行末にスペース2つが必要だった改行処理を、自動で行ってくれる設定。これを入れるだけで、素直なMarkdownが素直な出力になる。

私の知人も、これを知らずに苦労していた一人だ。「何度書いても文章が詰まる」と相談された時、configの設定を見直すようアドバイスした。案の定、それで一発解決だった。

以下は、新しい設定を適用した後のMarkdown記述例と出力結果だ。

これは1行目です。
これは2行目です。

これはスペース2つを使った改行。
次の行に移ります。

HTMLタグも使えます。
これは<div>で囲んだブロックです。

これは1行目です。
これは2行目です。

これはスペース2つを使った改行。
次の行に移ります。

HTMLタグも使えます。
これは<div>で囲んだブロックです。

意図通りの出力が得られたときの安心感は、Hugoを本格導入する大きな一歩になる。

テーマによっては、Markdownの設定が効いていても、CSSで改行が潰されるケースがある。その代表例がwhite-spaceプロパティだ。

p {
  white-space: pre-wrap;
}

この一行があるだけで、改行も空白も“そのまま”表示される。
実際、私の使っていたテーマでも、これを追記した途端、表示が劇的に改善された。

もしそれでも表示が崩れる場合、テーマのテンプレートファイルに原因があるかもしれない。意図せぬフィルタ処理がテンプレート内で行われているケースもあるため、部分的にオーバーライドするか、明示的に自作テンプレートに差し替えるという選択肢も検討したい。

静的サイトジェネレーターの中でも圧倒的なスピードを誇るHugoだが、Markdownの取り扱いにはコツが必要である。
以下の3ステップで、MarkdownとHTMLを思い通りに扱えるようになる：

config.yamlに以下を記述する

markup:
 goldmark:
   renderer:
     unsafe: true
   parser:
     hardLineBreak: true

ちょっとした設定変更が、大きな差を生む。
Hugoでの開発をさらに快適にするために、ぜひ今日からこの設定を取り入れてみてほしい。