【HUGO】マークダウンの中にHTMLコードを書いて表示する方法

マークダウンの中にHTMLコードを埋め込んで、そのまま表示してもらう方法です。

マークダウンにHTMLコードを書きます（結論）
1. マークダウンの仕様
2. HUGOのバージョン
マークダウン記法とHTMLタグの混在に問題はないのか？
問題はあったのはどんな時か？
ショートコードでHTMLコードを囲む
以上です。
.Inner って何？
ショートコードの名前は決まってるの？
素のHTMLをショートコードで囲んで出力するメリットは？
ショートコードで囲んでいるのに余計なタグがつく

マークダウンにHTMLコードを書きます（結論）

以上です。

いきなり結論ですが、マークダウンの中にHTMLタグをそのまま書けばOKでした。

HUGOは、マークダウンの中に書いたHTMLコードをそのまま出力してくれました。

マークダウンファイル(.md) の中に書くHTMLコードは、Raw HTML とか Inline HTML と呼ばれていました。

検索で『markdown raw html』とか『markdown inline html』で検索したら、『マークダウンはインラインHTMLをサポートしている』といった内容のサイトがヒットしました。

マークダウンの仕様

Markdownマークダウンの仕様（文法、構文、Syntaxシンタックス）の場所です（マークダウンの開発者のサイト）。

INLINE HTMLの説明がありました。

(daringfireball.net) INLINE HTML – Markdown Syntax Documentation

この場所を見て『マークダウンの文法がカバーしていないところは単にHTMLで書けば良い。（混在OK）』と自分は理解しました。

HUGO は（Blackfriday や Goldmark は）、そういったマークダウンの仕様をサポートしているようでした。

HUGOのバージョン

『hugo_0.54.0_Windows-64bit.zip』を自分は使っていました（記事執筆時点）。

『HUGO v0.60.0』以降は、初期設定だとHTMLが出なくなりました。

goldmarkの設定(config.toml)で『unsafe: true』を設定すると、従来通りマークダウン中のHTMLが出せました。

(gohugo.io) unsafe: true (config.yaml, toml, json)

それにしても Goldmark、凄いです。

マークダウン記法とHTMLタグの混在に問題はないのか？

ほとんど問題なかったです。

自分も強調タグ『』を使い分けたい時などに、マークダウン記法の『**』で囲んだり、HTMLタグ『』で囲んだりして来ましたが、特に問題はありませんでした。

問題はあったのはどんな時か？

たとえば、アンカータグ『<a>』だけの行があると、それがパラグラフタグ『』で囲まれてしまいました。

マークダウン(.md)

<a href="/">ＸＸ株式会社</a>

HUGOの出力(.html)

<p><a href="/">ＸＸ株式会社</a></p>

HUGOが出力したサイトを見て、<a>タグのまわりに余分な余白ができていたので気づきました。

これは、『リンク化した画像をページの幅いっぱいに表示したい』といった場合に困りました。

タグのスタイルに由来する余白（マージン）が左右に追加されてしまったからです。

文章中のリンクなら適切なんですけどね。

中には、タグを追加してほしくない場合もあったわけです。

どうすればいいか？

ショートコードでHTMLコードを囲む

静的サイトジェネレーターのHUGO（ヒューゴ）には、ショートコードに、素のHTMLをそのまま出力してくれる機能がありました。

ドットインナー変数 {{ .Inner }} と {{< >}} です。これらを使います。

具体的な方法です。

ショートコードを作ります

『layouts』の中の『shortcodes』フォルダに、『rawhtml.html』という名前のファイルを作ります（ファイル名はなんでもOKです）。

このファイルの中に、ドットインナー変数 {{ .Inner }} を１つ書きます。

１行だけです。改行も不要でした。

{{ .Inner }}

マークダウンにHTMLを書いて囲みます

.md ファイルにHTMLコードを直接書いて、それをショートコードで囲みます。

こんな感じです。

マークダウン(.md)

{{< rawhtml >}}<a href="/">ＸＸ株式会社</a>{{< /rawhtml >}}

HUGOの出力(.html)

<a href="/">ＸＸ株式会社</a>

タグが消えました。

{{< >}} と {{% %}} の説明

HUGOの解釈（レンダリング）を避けるときは {{< >}} のほうを使用します。

(gohugo.io) {{< >}} Shortcodes Without Markdown

一方で、パーセント記号の {{% %}} だとマークダウンとしての解釈が入りました。

(gohugo.io) {{% %}} Shortcodes with Markdown

以上です。

ざっくり、まとめです。

マークダウンとHTMLタグは混在OKで、HTMLで書きたいところはHTMLで書けばそのまま出力してくれました。

HUGOも、そういった書き方に対応しているようでした。

でも、意図した動作にならないこともありました。

マークダウンに書いたHTMLの出力に、問題があった時の回避方法です。

{{ .Inner }} だけのショートコードを作って、開始ショートコードと終了ショートコードで囲みます。

これで、書いた内容をそのまま出力してくれました。

本文はマークダウンで書いて、複雑なところはHTMLコードで書く。
上手く行かないときは、ショートコードで囲む。

これで、書きたいことは、マークダウンでほぼ表現できるようになりました。

以下補足です。

.Inner って何？

『開始ショートコード』と『終了ショートコード』で囲んだ部分の文字列を出力する変数です。

HUGOの標準機能です。

{{< >}} で呼び出せば、囲った部分がそのまま出力されるので、HTMLコードを囲めばHTMLコードがそのまま出力されるという寸法です。

.Inner の説明は以下のページにありました。

(gohugo.io) Shortcode Variables .Inner

(gohugo.io) Create Your Own Shortcodes .Inner

ショートコードの名前は決まってるの？

特に決まりは無かったです。

ショートコードのファイル名は何でもOKでした。

ここでは『rawhtml.html』で作りましたが、もっと短い名前にしても大丈夫です。

自分は raw.html とか r.html みたいなファイル名で {{ .Inner }} のショートコードを作って使っています。

素のHTMLをショートコードで囲んで出力するメリットは？

HUGOの解釈を避けることができたので、素のHTMLコードに余計なタグがつかないメリットがありました。

かといって、マークダウンの中のHTMLコードを、全部ショートコードで囲む必要はないと思います。

中には意図しないHTMLになるケースがあったというだけで、独立した行の<a>タグがタグで囲まれるのも、テキストリンクなら適切な動作だと思います。

ショートコードで囲んでいるのに余計なタグがつく

ショートコードで囲んでも、タグがつく場合がありました。

ショートコードとショートコードの間は、１行あける必要がありました。

１行あけたら、タグが付かなかったです。

行をあけないと

{{< rawhtml >}}<a href="/">あああ</a>{{< /rawhtml >}}
{{< rawhtml >}}<a href="/">いいい</a>{{< /rawhtml >}}

<p>タグが付く

<p><a href="/">あああ</a>
<a href="/">いいい</a></p>

行をあければ

{{< rawhtml >}}<a href="/">あああ</a>{{< /rawhtml >}}

{{< rawhtml >}}<a href="/">いいい</a>{{< /rawhtml >}}

何も付かない

<a href="/">あああ</a>

<a href="/">いいい</a>

以上です。