本記事の概要
Hugoのショートコードの入門となる初心者向けの記事です。
何回かに分けて投稿する予定です。
前提
Hugo+Blowfishテーマ適用済みの環境です。
なお、Windowsでの操作を想定しています。
(本記事が属するアドベントカレンダーについてもご確認ください)
ShortCodeとは
簡単に言えば、記事のMarkdown内からテンプレート的な記載を呼び出して埋め込める機能です。
ShortCodeには引数もつけられるので、拡張性もあります。
もちろん、Hugoやテーマに組み込み済みのShortCodeもありますし、それでも足りなければ自作できます。
詳細は下記のHugo公式を読むと良いです。
簡単なShortCodeを作ってみる
ここでは、ルビを付けるという簡単なShortCodeを作ることで入門したいと思います。
さて、Day6でも書いた通りに、Markdownは最終的にHTMLに変換されること、またHTMLを直接埋め込めるということがミソになります。
という訳で、特定の(今回ならルビ)機能を持ったHTMLタグを埋め込むShortCodeを作れば、簡単に実現できるという訳です。
HTMLでルビを振るには？
HTMLでルビを振るにはrubyタグを使えば良いです。
タグとしての説明はMDNの記載が詳細に書かれています。
「本気」と書いて「マジ」と読むという例で、タグを書いてみるとこんな感じになります。
rubyタグの中に文章を、そしてその中にrtタグを入れてルビを入れる形です。
<ruby>本気<rt>マジ</rt></ruby>
実際に書くと「本気」という感じになります。
上記のMDNにも書かれていますが、現在ではほとんどのブラウザーでrubyタグはサポートされています。
念のためサポートされていないブラウザーも考慮した書き方が出来ると安心です。
rubyタグに対応していないブラウザーも考慮する場合、rpタグを使用します。
再び、「本気」と書いて「マジ」と読むという例で書くと下記のようになります。
<ruby>本気<rp>(</rp><rt>マジ</rt><rp>)</rp></ruby>
rubyタグに対応している場合は上記と同じ表示になりますが、
対応していない場合は「本気(マジ)」という風に表示されます。
ルビに対応している場合はrpタグの中身が無視され、
対応していない場合はrtタグの中身が本文の上ではなく、直後に表示される。
といったイメージです。
ShortCodeを作ってみる
ShortCodeはHugoのビルド環境の「layouts/shortcodes」ディレクトリ内に作成します。
フォルダ名を間違えると使用できません。
ShortCodeの拡張子は.htmlです。
このフォルダ内にruby.htmlを作り、下記のように書いてみましょう。
このファイル名が呼び出すときに使用する名前になります。
<ruby>{{- (.Get 0) -}}<rp>(</rp><rt>{{- (.Get 1) -}}</rt><rp>)</rp></ruby>
先程の「本気」や「マジ」の部分が(.Get 0)や(.Get 1)という風に変わった形です。
(.Get 0)や（.Get 1)は、使うときに0番目の引数や1番目の引数に置き変わります。
Hugoの引数は0番目からカウントされます。
ただし、これらはHTMLタグではなく、Hugoの機能であるため、「{{-」と「-}}」で囲む必要があります。
※大元としてはGo言語のHTMLテンプレートの機能です。
使ってみる
記事のMarkdownから下記のように書いてみましょう。
ShortCodeを呼び出すときは、「{{<」から始め、「ショートコード名」、 「(必要であれば引数」、「>}}」という流れで書きます。
{{< ruby "本気" "マジ" >}}
下記の様にルビが表示されたら成功です！
ShortCodeを使うことで、HTMLタグを使わなくてもルビが振れるようになりました。
表記もシンプルなので、直感的に書くことが出来ます。
これ以外にも、ShortCodeを使うことで、効率的にHTMLタグを埋め込めます。
次回以降
このShortCodeを拡張しながら細かい機能を説明したいと思います。