本記事の概要
Hugo+BlowfishテーマでのMarkdownの基本について記載する。
前提
Hugo+Blowfishテーマ適用済みの環境です。
なお、Windowsでの操作を想定しています。
(本記事が属するアドベントカレンダーについてもご確認ください)
参考：Blowfish公式のMarkdownレンダリングサンプル
以下の公式サイトにMarkdownのレンダリング結果が記載されている。
Markdownとは？
平たく言えば「ほぼ普通のテキストなのに、HTMLに変換できる」テキストファイルと言えばよいだろう。
Markdownを使うことにより、
- 執筆時
- ほぼ普通のテキストとして書くことができる(HTMLのタグ手打ち不要)
- 閲覧時
- HTMLに変換することによりリッチな見た目で表示できる
という形になる。
そのため、ブログであれば記事の執筆など、書くことに専念が出来るので、効率的にサイトを作成できる。
Markdownの詳細についてはWikipedia等で調べると良い。
HugoのMarkdownについて
Markdown自体は、QiitaやGitHubなどあちこちで使われている。
そのため、モノによって細かい文法の違い(方言の様なもの)がある。
ただし、大部分は共通しているので、どこかで一度覚えているのであればほぼ問題無いだろう。
要は、Markdownの(レンダラー：変換ソフト)の違いやコンフィグ設定に起因する話である。
ちなみに、公式サイトにも記載されているが、HugoではGoldmarkというソフトが使われている。
Blowfishテーマの設定について
Blowfishテーマにおいては、config/_default/markup.toml内にGoldmarkの設定が行われている。
通常の使用においてこの中身を書き換えることがあまりないが、Blowfishではデフォルトでunsafe設定がなされている。
これは、Markdownの中にHTMLタグをベタ書き出来る という意味である。
他テーマへ移行した際にうまくHTMLタグが表示されなければ、この辺りの設定差異を確認すると良いだろう。
# -- Markup --
[goldmark]
[goldmark.renderer]
unsafe = true
実際にやってみる
Day4で作ったtest.mdを書き換える形で、トライしてみることにする。
ポイント
MarkdownはテキストからHTMLに変換するため、変換後のHTMLのタグに対応する記法が多数存在する。
そのため、タグについてわからなければ、MDNなどで対応するHTMLのタグを調べると良い。
見出し
HTMLには、<h1>～<h6>までの見出しタグが存在する。
h1が最上位でh6が最下位である。
通常、見出しはブログで言えばタイトルや、記事内のセクションなどに使われる。
参考：HTMLとしての詳細はMDNを参照すると良い。
Markdownで見出しを書くには、行頭に「#」の文字を1～6個並べればよい。
1個ならば、h1だし、6個ならh6である。
その後、半角スペースを1個入れてから見出しのタイトルを書けば良い。
# h1見出し
## h2見出し
### h3見出し
#### h4見出し
##### h5見出し
###### h6見出し
Blowfishテーマにおいては、h2～h4 の範囲にとどめておくと良い。
Blowfishテーマには見出しに沿って目次を生成する機能があるのだが、h2～h4までしか対応していない ためである。
上述のBlowfishのMarkdownサンプルをよく見るとそうなっているが、文章として残っていないので明記しておく。
段落
文章と文章の間に空行を空けることで、段落を作れる。
なお、文章に対して改行を入れたければ、行の末尾に半角スペースを2つ入れると改行される。
1段落目の文章です。末尾に半角スペース2つ入れて改行を入れてます
まだまだ1段落目です。
空行を入れたので2段落目です。
先にも言った通り、Blowfishテーマのデフォルト設定では、HTMLタグを受け付ける設定になっているので、個人サイトなどでは別に</br>で改行を入れる手もある。
(厳密に言えばCSSで調整すべきことではあるが)
文章1
</br>
文章2
順序無しリスト
「-」、「+」、「*」のいずれかを書いたのちに、半角スペース1個を入れて項目を書くことで、順序無しリストが作れる。
(どの記号を使っても同じである)
先頭に半角スペース2個を入れるとインデントできる。
- 1個目
- インデントを入れる
+ 1個目
+ 2個目
* 1個目
* 2個目
* 3個目
といった形に書く。
順序付きリスト
「1.」、「2.」. 「3.」～という風に書いたのちに、半角スペース1個を入れて項目を書くことで、順序無しリストが作れる。
ただし、数字のインクリメントなどが手間なので、全て1.としても良い。
(どちらかというと全て1.とした方が楽である。
1. 1個目
1. 2個目
1. 3個目
リンク
普通にURLを貼るとリンクが出来る。
(リンクが出来ない場合は、空行を入れたり、URLの前後に半角スペースを入れると良い。
https://qiita.com
また、以下のように書くことで、画面では「こちら」と表示されているが、クリックするとqiitaにジャンプするリンクが作れる。
ちなみに、[]と()の中に同じURLを入れれば、先に示した場合と同じ結果になる。
上記の方法でURL化できない環境などがあれば、この方法をとると良い。
[「こちら」](https://qiita.com)
太字と斜体
太字にしたい場合、その部分を「__」もしくは「**」で囲むと太字になる。
斜体にしたい場合、その部分を「_」もしくは「*」で囲むと斜体になる。
日本語などを含む場合、開始記号の直前や終了記号の直後に半角スペースを入れないと認識しない場合がある。
こうすれば、 __太字__ に出来ます。
こうしても、 **太字** に出来ます。
こうすれば、 _斜体_ に出来ます。
こうしても、 *斜体* に出来ます。
ここまでのまとめ
まとめると下記のようになる。
# h1見出し
## h2見出し
### h3見出し
#### h4見出し
##### h5見出し
###### h6見出し
1段落目の文章です。末尾に半角スペース2つ入れて改行を入れてます
まだまだ1段落目です。
空行を入れたので2段落目です。
- 1個目
- インデントを入れる
+ 1個目
+ 2個目
* 1個目
* 2個目
* 3個目
1. 1個目
1. 2個目
1. 3個目
https://qiita.com
[「こちら」](https://qiita.com)
こうすれば、 __太字__ に出来ます。
こうしても、 **太字** に出来ます。
こうすれば、 _斜体_ に出来ます。
こうしても、 *斜体* に出来ます。
上記Markdownは、下記の様に表示される。
おまけ：HTMLの埋め込み機能について
Googleマップやnoteなど、世の中にはHTMLファイルの埋め込み機能に対応しているページが多数存在する。
Googleマップでの埋め込み機能の例(札幌駅と検索した場合)
先にも言った通り、Hugo+BlowfishテーマのMarkdownはHTMLタグの埋め込みに対応しているため、このような埋め込み機能を使いたければ、単にHTMLをコピーして記事に貼り付けば良い。
<iframe src="https://www.google.com/maps/embed?pb=!1m18!1m12!1m3!1d4835.071402468324!2d141.34663542695316!3d43.0686606!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!3m3!1m2!1s0x5f0b2974d2c3f903%3A0xa5e2b18cdd4a47a5!2z5pyt5bmM6aeF!5e1!3m2!1sja!2sjp!4v1764950085247!5m2!1sja!2sjp" width="400" height="300" style="border:0;" allowfullscreen="" loading="lazy" referrerpolicy="no-referrer-when-downgrade"></iframe>
まとめ
Hugo + BlowfishテーマにおけるMarkdownの基本について記載した。
他にも文法はあるので興味があれば調べてみると面白いが、上記の内容を最低限覚えておくとHugo以外でMarkdownを使う際にも使える。