Hugoで記事を書いていると、「ここにYouTube動画のプレーヤーを埋め込みたい」「目立つデザインの警告ボックス（Alert）を挿入したい」といったように、Markdownの基本文法だけでは表現しきれないレイアウトが必要になる場面があります。
そんな時に大活躍するのが 「ショートコード (Shortcode)」 機能です。

この記事では、標準搭載のショートコードの使い方と、サイト独自のリッチなHTML装飾をMarkdownから一発で呼び出せる「自作ショートコード」の作り方を解説します！

1. Hugo標準のショートコード

Hugoには、最初から便利なショートコードがいくつか用意されています。
自分で何も作らなくてもすぐに使えます。

YouTubeを表示する

動画のID（URLの v= の後ろの部分）を指定するだけです。

{{< youtube "w7Ft2ymGmfc" >}}

実際の表示:

X (旧 Twitter) を埋め込む

ツイートのURL末尾の数字部分 (ID) を指定します。

{{< tweet "1234567890" >}}

Instagram を埋め込む

投稿ID（URLの p/ の後ろの英数字）を指定します。

{{< instagram "BWNJJyYFxVx" >}}

その他の標準ショートコード

Hugoには他にも便利なショートコードが用意されています。

  • figure: 画像をキャプション付きで表示する（超便利！）
  • gist: GitHub Gistのコードを表示する
  • vimeo: Vimeoの動画を表示する
  • param: 記事のFront Matterパラメータを表示する

詳しくは Hugo公式サイトのShortcodes一覧 も見てみてください。

2. 自作ショートコード：警告ボックスを作ろう

標準機能だけでは物足りない時は、自分で作っちゃいましょう！
今回は、記事の中で目立つ 「警告ボックス (Alert Box)」 を作ります。

テンプレート作成

themes/my-tutorial-theme/layouts/shortcodes/ フォルダに alert.html を作成します。

<div class="alert {{ .Get "class" }}">
    <div class="alert-title">{{ .Get "title" }}</div>
    <div class="alert-content">
        {{ .Inner | markdownify }}
    </div>
</div>
  • {{ .Get "..." }}: ショートコードの引数を受け取ります。
  • {{ .Inner }}: ショートコードで囲んだ中身（テキスト）を受け取ります。

CSSで装飾

static/css/style.css に、デザイン用のCSSを追加します。
（今回は青色の info、黄色の warning、赤色の danger を用意しました！）

/* アラートボックスの共通スタイル */
.alert {
    padding: 15px;
    margin-bottom: 20px;
    border: 1px solid transparent;
    border-radius: 4px;
}

.alert-title {
    font-weight: bold;
    display: block;
    margin-bottom: 5px;
}

/* Info (青) */
.alert.info {
    color: #31708f;
    background-color: #d9edf7;
    border-color: #bce8f1;
}

/* Warning (黄) */
.alert.warning {
    color: #8a6d3b;
    background-color: #fcf8e3;
    border-color: #faebcc;
}

/* Danger (赤) */
.alert.danger {
    color: #a94442;
    background-color: #f2dede;
    border-color: #ebccd1;
}

使い方

記事（Markdown）の中で、以下のように書きます。

{{< alert class="warning" title="ここにタイトル" >}}
ここは **Markdown** も使えます！
重要なメッセージをここに書きましょう。
{{< /alert >}}

3. 実際のデモ

では、実際に使ってみましょう！
コードと表示結果を見比べてみてください。

Info（情報）

{{< alert class="info" title="豆知識 💡" >}}
これは `class="info"` で作った青いボックスです。
ちょっとした補足情報に便利ですね。
{{< /alert >}}

👇 表示結果:

豆知識 💡
これは class="info" で作った青いボックスです。
ちょっとした補足情報に便利ですね。

Warning（注意）

{{< alert class="warning" title="注意点 ⚠️" >}}
これは `class="warning"` です。
「ここテストに出るよ！」みたいな時に使いましょう。
{{< /alert >}}

👇 表示結果:

注意点 ⚠️
これは class="warning" です。
「ここテストに出るよ！」みたいな時に使いましょう。

Danger（危険）

{{< alert class="danger" title="危険！ 🔥" >}}
これは `class="danger"` です。
**データのバックアップ** を忘れないで！といった重大な警告に使います。
{{< /alert >}}

👇 表示結果:

危険！ 🔥
これは class="danger" です。
データのバックアップ を忘れないで！といった重大な警告に使います。

4. 補足ボックス (Note)

「注意書き」や「ヒント」を目立たせたい時に便利です。

使い方

Markdownファイルにこう書くと…

{{< note title="ポイント" type="info" >}}
ここは重要なポイントです！
背景色がつきます。
{{< /note >}}

{{< note title="危険！" type="alert" >}}
これは警告メッセージです。赤くなります。
{{< /note >}}

実装方法

themes/my-tutorial-theme/layouts/shortcodes/note.html を作成し、以下のコードを保存します。

<div class="shortcode-note {{ .Get "type" | default "info" }}">
    <div class="note-title">{{ .Get "title" | default "Note" }}</div>
    <div class="note-content">
        {{ .Inner | markdownify }}
    </div>
</div>

<style>
/* CSSは本来 style.css に書くべきですが、簡単のためここに書いています */
.shortcode-note {
    border: 1px solid #ddd;
    border-left: 5px solid #2196F3;
    background-color: #f9f9f9;
    margin: 1.5rem 0;
    padding: 1rem;
    border-radius: 4px;
}
.shortcode-note.warning {
    border-left-color: #ff9800;
    background-color: #fff3e0;
}
.shortcode-note.alert {
    border-left-color: #f44336;
    background-color: #ffebee;
}
.note-title {
    font-weight: bold;
    margin-bottom: 0.5rem;
    color: #555;
}
</style>

5. 会話形式の吹き出し (Balloon)

対談形式の記事や、キャラクターに喋らせたい時に使えます。

使い方

{{< balloon name="太郎" img="/images/user.png" side="left" >}}
こんにちは！今日はHugoについて勉強しましょう。
{{< /balloon >}}

{{< balloon name="先生" img="/images/teacher.png" side="right" >}}
いいですね！まずはショートコードから始めましょう。
{{< /balloon >}}

準備: static/images/ フォルダにアイコン画像 (user.png など) を置いておいてくださいね。

実装方法

themes/my-tutorial-theme/layouts/shortcodes/balloon.html を作成し、以下のコードを保存します。

（コードが長くなるので詳細は省略しますが、div タグと flexbox を使ってアイコンとテキストを横並びにしています）
※ このテーマには既に実装済みですので、ファイルの中身を確認してみてください！

オリジナルのショートコードでMarkdown記事の表現力を広げよう

ショートコードを活用すれば、複雑なHTMLタグやCSSクラスをMarkdownファイル内に毎回手書きする必要がなくなります。また、後からデザインを変更したくなった際も、ショートコードのHTMLテンプレートを1箇所書き換えるだけで過去の全記事に自動反映されるため、運用効率が劇的に上がります。

YouTubeやX(Twitter)の埋め込みといったHugo標準機能だけでなく、「警告ボックス」や「キャラクターの会話吹き出し」など、自分のブログでよく使う独自のデザインパターンはどんどんショートコード化して、執筆作業を楽にしていきましょう！🚀