マークダウンの中にHTMLコードを埋め込んで、そのまま表示してもらう方法です。
マークダウンにHTMLコードを書きます
以上です。
いきなり結論ですが、マークダウンの中にHTMLタグをそのまま書けばOKです。
HUGOは、マークダウンの中に書いたHTMLコードをそのまま出力してくれます。
マークダウンファイル(.md) の中に書くHTMLコードは、Raw HTML とか Inline HTML と呼ばれているようです。
検索で『markdown raw html』とか『markdown inline html』で検索すれば、『マークダウンはインラインHTMLをサポートしている』といった内容のサイトがヒットします。
HUGOは、そういったマークダウンの仕様をサポートしているわけです。
マークダウン記法とHTMLタグの混在に問題はないのか？
ほとんど問題ありません。
私も強調タグ『<b><em><strong>』を使い分けたい時などに、マークダウン記法の『**』で囲んだり、HTMLタグ『<b></b>』で囲んだりして来ましたが、特に問題はありませんでした。
問題はあるのはどんな時か？
たとえば、アンカータグ『<a>』だけの行があると、それがパラグラフタグ『<p>』で囲まれてしまいます。
マークダウン(.md)
<a href="/">ＸＸ株式会社</a>HUGOの出力(.html)
<p><a href="/">ＸＸ株式会社</a></p>HUGOが出力したサイトを見て、<a>タグのまわりに余分な余白ができていたので気づきました。
これは、『リンク化した画像をページの幅いっぱいに表示したい』といった場合に困ります。
<p>タグのスタイルに由来する余白（マージン）が左右に追加されてしまうからです。
文章のリンクなら適切なんですけどね。中には<p>タグを追加してほしくない場合もあるわけです。
どうすればいいか？
ショートコードでHTMLコードを囲む
静的サイトジェネレーターのHUGO（ヒューゴ）には、ショートコードに素のHTMLをそのまま出力してくれる機能があります。
ドットインナー変数 {{ .Inner }} です。これを使います。
具体的な方法です。
ショートコードを作ります
『layouts』の中の『shortcodes』フォルダに、『rawhtml.html』という名前のファイルを作ります。
このファイルの中に、ドットインナー変数 {{ .Inner }} を１つ書きます。
１行だけです。改行も不要です。
{{ .Inner }}マークダウンにHTMLを書いて囲みます
.md ファイルにHTMLコードを直接書いて、それをショートコードで囲みます。
こんな感じです。
マークダウン(.md)
{{< rawhtml >}}<a href="/">ＸＸ株式会社</a>{{< /rawhtml >}}HUGOの出力(.html)
<a href="/">ＸＸ株式会社</a>
<p> タグが消えました。
以上です。
ざっくり、まとめです。
マークダウンとHTMLタグは混在OKで、HTMLで書きたいところはHTMLで書けばそのまま出力してくれる。HUGOもそれに対応している。
でも、意図した動作にならないこともある。
マークダウンに書いたHTMLの出力に問題がある時の回避方法です。
{{ .Inner }} だけのショートコードを作って、開始ショートコードと終了ショートコードで囲めば、そのまま出力してくれます。
本文はマークダウンで書いて、複雑なところはHTMLコードで書く。上手く行かないときは、ショートコードで囲む。
これで、書きたいことはマークダウンでほぼ表現できるようになりました。
以下補足です。
.Inner って何？
『開始ショートコード』と『終了ショートコード』で囲んだ部分の文字列を出力する変数です。HUGOの機能です。
囲った部分がそのまま出力されるので、HTMLコードを囲めばHTMLコードがそのまま出力されるという寸法です。
.Inner の説明は以下のページにありました。
HUGO 公式マニュアル
Shortcode Variables .Inner
Create Your Own Shortcodes .Inner
ショートコードの名前は決まってるの？
ショートコードのファイル名は何でもOKです。
ここでは『rawhtml.html』で作りましたが、もっと短い名前にしても大丈夫です。
素のHTMLをショートコードで囲んで出力するメリットは？
HUGOの解釈を避けることができるので、素のHTMLコードに余計なタグがつかないメリットがあります。
かといって、マークダウンの中のHTMLコードを全部ショートコードで囲む必要はないと思います。
中には意図しないHTMLになるケースがあるというだけで、独立した行の<a>タグが<p>タグで囲まれるのも、テキストリンクなら適切な動作だと思います。
ショートコードで囲んでいるのに余計なタグがつく
ショートコードで囲んでも、<p>タグがつく場合があります。
ショートコードとショートコードの間は１行あける必要があります。
１行あければ、<p>タグが付かないようです。
行をあけないと
{{< 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>HUGOのバージョン
『hugo_0.54.0_Windows-64bit.zip』を使いました。
