マークダウンの中に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 公式マニュアル
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』を使いました。
