本記事の概要

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タグのシンプルなサンプル

<ruby>本気<rt>マジ</rt></ruby>

実際に書くと「本気マジ」という感じになります。

上記のMDNにも書かれていますが、現在ではほとんどのブラウザーでrubyタグはサポートされています。
念のためサポートされていないブラウザーも考慮した書き方が出来ると安心です。
rubyタグに対応していないブラウザーも考慮する場合、rpタグを使用します。
再び、「本気」と書いて「マジ」と読むという例で書くと下記のようになります。

rpタグも利用したサンプル

<ruby>本気<rp>(</rp><rt>マジ</rt><rp>)</rp></ruby>

rubyタグに対応している場合は上記と同じ表示になりますが、
対応していない場合は「本気(マジ)」という風に表示されます。

ルビに対応している場合はrpタグの中身が無視され、
対応していない場合はrtタグの中身が本文の上ではなく、直後に表示される。
といったイメージです。

ShortCodeを作ってみる

ShortCodeはHugoのビルド環境の「layouts/shortcodes」ディレクトリ内に作成します。

フォルダ名を間違えると使用できません。

ShortCodeの拡張子は.htmlです。
このフォルダ内にruby.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を拡張しながら細かい機能を説明したいと思います。