マークダウンの中に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タグの混在に問題はないのか?
ほとんど問題なかったです。
自分も強調タグ『<b><em><strong>』を使い分けたい時などに、マークダウン記法の『**
』で囲んだり、HTMLタグ『<b></b>』で囲んだりして来ましたが、特に問題はありませんでした。
問題はあったのはどんな時か?
たとえば、アンカータグ『<a>』だけの行があると、それがパラグラフタグ『<p>』で囲まれてしまいました。
マークダウン(.md)
<a href="/">XX株式会社</a>
HUGOの出力(.html)
<p><a href="/">XX株式会社</a></p>
HUGOが出力したサイトを見て、<a>タグのまわりに余分な余白が余計にできていたので気づきました。
これは、『リンク化した画像をページの幅いっぱいに表示したい』といった場合に困りました。
<p>タグのスタイルに由来する余白(マージン)が左右に追加されてしまったからです。
文章中のリンクなら適切なんですけどね。
中には、<p>タグを追加してほしくない場合もあったわけです。
どうすればいいか?
ショートコードでHTMLコードを囲む
静的サイトジェネレーターのHUGO(ヒューゴ)には、ショートコードに、素のHTMLをそのまま出力してくれる機能がありました。
ドットインナー変数 {{ .Inner }} と {{< >}} です。これらを使います。
具体的な方法です。
ショートコードを作ります
『layouts』の中の『shortcodes』フォルダに、『rawhtml.html』という名前のファイルを作ります(ファイル名はなんでもOKです)。
このファイルの中に、ドットインナー変数 {{ .Inner }} を1つ書きます。
1行だけです。改行も不要でした。
{{ .Inner }}
マークダウンにHTMLを書いて囲みます
.md ファイルにHTMLコードを直接書いて、それをショートコードで囲みます。
こんな感じです。
マークダウン(.md)
{{< rawhtml >}}<a href="/">XX株式会社</a>{{< /rawhtml >}}
HUGOの出力(.html)
<a href="/">XX株式会社</a>
<p> タグが消えました。
{{< >}} と {{% %}} の説明
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>タグが<p>タグで囲まれるのも、テキストリンクなら適切な動作だと思います。
ショートコードで囲んでいるのに余計なタグがつく
ショートコードで囲んでも、<p>タグがつく場合がありました。
ショートコードとショートコードの間は、1行あける必要がありました。
1行あけたら、<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>
以上です。