Hugo を使っていく上で重要そうな Shortcode の使い方や作り方の例について、初心者目線でまとめてみました。

今回は Hugo に備え付けの Shortcode の 紹介から簡単な Shortcode の作り方などをご紹介します。

Shortcode とは何か？

WordPress にも同名の機能がある

Shortcode について調べてみると WordPress 関連の情報が多数ヒットします。

使い方としては似ている面もあるのかもしれませんが、 書き方や機能の面では異なっているようです。

本記事ではこれ以降 WordPress については触れず、 Hugo における Shortcode について述べます。

Markdown ではできないことが可能になる

Markdown は楽です。 直接 HTML を書く場合と比べて圧倒的に読みやすく、シンプルです。

Hugo でもこの Markdown が勧められていますが、 Markdown だけでは実現できないものがあるのも事実です。

このような場合に登場するのが Shortcode です。

Shortcodeとは： HTML を埋め込めるスニペット（テンプレート）機能

Shortcode は、 あらかじめ設定したテンプレートを使ってレンダリングしてくれる機能です。

HTML を埋め込むことができて、さらにマクロのような機能もあるイメージでしょうか。

Shortcode の使い方

Markdown ファイル内で次のように記述する呼び出すことができます。

{{< 名前 [パラメータ]　>}}

もしくは次のように、 HTML タグのように呼び出す場合もあります。

{{< 名前 [パラメータ]　>}}

内容

{{< /名前 >}}

Hugo 備え付けの Shortcode について

公式のドキュメントはこちらです。

数はそれほど多くなさそうですね。

紹介されているものは以下です。

  • figure
  • gist
  • highlight
  • instagram
  • param
  • ref and relref
  • tweet
  • vimeo
  • youtube

試してみる（Gist の例）

公式 Docs にあるように、 Gist を表示してみようと思います。

以下のように Markdown 内で記述します。

{{< gist spf13 7896402 “img.html” >}}

表示される内容がこちら。

いい感じに表示してくれていますね。便利そうです。

ちなみに上記の Gist は、画像を貼り付ける Shortcode のテンプレートの内容になっています。

Shortcode を実際に書いてみる

ファイルの置き場所について

Shortcode は layouts/shortcodes ディレクトリ内に(呼び出し時の名前).html として配置します。

ディレクトリが存在しない場合は作成する必要があります。

使っているテーマ( theme )や Hugo にもとから備わっている Shortcode と同名の Shortcode を作ると上書きすることができます。

吹き出しを作ってみる

早速ですが、例として画像と吹き出しを作ってみたいと思います。

最近のブログ記事などで見かけるようなやつですね。

作成したものがこちら。

Shortcode で吹き出しを作ってみました。

Markdown を入れ子にすることができます。

見出し(h3)

見出し(h4)

  • リスト1
    • リスト1.1
  • リスト2
コード

画像と向きを変えてみる

これを生成する Markdown の記述が以下です。

{ を {{に、 } を }}に読み変えてください。

markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{ fukidashi position="left" path="dogs/dog1_smile.png"}
Shortcode で吹き出しを作ってみました。

Markdown を入れ子にすることができます。

### 見出し(h3)
#### 見出し(h4)

- リスト1
  - リスト1.1
- リスト2

```
コード
```

{< /fukidashi >}

{< fukidashi position="right" path="dogs/dog3_1_question.png" >}
画像と向きを変えてみる
{< /fukidashi >}

楽しい

吹き出しのコードを紹介　

それでは実際のコードを見ていきましょう。

テンプレート部分

テンプレート部分がこちらです。

/layouts/shortcodes/fukidashi.html
1
2
3
4
5
6
7
8
<div class="fukidashi-wrapper {{ .Get "position" }}">
  <figure class="fukidashi-figure">
    <img class="fukidashi-image" src="{{$.Site.Params.imageBasePath}}{{.Get "path"}}">
  </figure>
  <div class="fukidashi-main fukidashi-main__{{.Get "position"}}">
    <p> {{ .Inner | markdownify }}</p>
  </div>
</div>

ほとんど HTML ですが、 {{ }} で囲ってある部分は Hugo の Templates の記法になっています。

詳しくはこちらの公式ドキュメントに記載されています。

画像として src または path というパラメータを取得するようにしており、 path の場合は相対パスでの指定が可能となっています。

path を使用する場合は config.toml に imageBasePath という項目を追加する必要がある点にご注意ください。

position として left または right を入力できるようにしています。

…なるほど、CSS のクラス部分も自由にパラメータとして変えられるんですね！

スタイルシート（CSS）部分

スタイルシートは次のようになりました。

ちなみに最近知ったのですが、 Hugo では SCSS が使えます。 以下も SCSS で記述されています。

/assets/fukidashi.scss
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
.fukidashi-wrapper {
  width: 100%;
  align-items: center;
  margin: 1.5em 0;
  display: flex;
}
.right {
  flex-direction: row-reverse;
}
.left {
  flex-direction: row;
}

figure.fukidashi-figure {
  width: 120px;
  height: 120px;
}

img.fukidashi-image {
  margin: 0 !important;
  width: 100%;
  height: 100%;
  object-fit: cover;
}

.fukidashi-main {
  position: relative;
  padding: 1.35em !important;
  display: inline-block;
  border-radius: 12px;
  min-width: 120px;
  color: #888;
  background: #fff;
  border: solid 3px #888;
  box-sizing: border-box;
  margin: 1.5em;
  &__left {
    max-width: calc(100% - 120px);
    &:before {
      content: "";
      position: absolute;
      top: 50%;
      left: -24px;
      margin-top: -12px;
      border: 12px solid transparent;
      border-right: 12px solid #fff;
      z-index: 2;
    }
    &:after {
      content: "";
      position: absolute;
      top: 50%;
      left: -30px;
      margin-top: -14px;
      border: 14px solid transparent;
      border-right: 14px solid #888;
      z-index: 1;
    }
  }
  &__right {
    max-width: calc(100% - 120px);
    &:before {
      content: "";
      position: absolute;
      top: 50%;
      right: -24px;
      margin-top: -12px;
      border: 12px solid transparent;
      border-left: 12px solid #fff;
      z-index: 2;
    }
    &:after {
      content: "";
      position: absolute;
      top: 50%;
      right: -30px;
      margin-top: -14px;
      border: 14px solid transparent;
      border-left: 14px solid #888;
      z-index: 1;
    }
  }
}

以上です。

SCSS に対応しているのはありがたいですね！

おわりに

今回は Hugo における Shortcode の使い方や作成方法について紹介しました。

作成した Shortcode は今後使っていこうと思います！