🚀 はじめに：この記事でできること
この記事は、Hugoのショートコード（Shortcodes）を使って、Markdown記事の表現力を高めるための完全ガイドです。
組み込みショートコードの使い方から、自作ショートコードの作成、PaperModでの最適化までを「操作→目的→結果→注意/補足」の順で、初心者でも迷わない構成で解説します。
補足
ショートコードは、YouTube埋め込み・画像最適化・カスタムHTMLの挿入・再利用可能なパーツ化などを簡単に実現できます。WordPressのショートコードに似ていますが、Hugoは高速でテンプレート連携が容易なのが特徴です。
🧭 前提：対象と環境
このガイドは Hugo + PaperMod + GitHub Pages でブログを運用する初心者〜中級者を対象に、記事内の表現力と保守性を高めるための実践的な手順をまとめています。
操作
- 作業環境：Hugo（最新安定版）・PaperModテーマ・GitHub Pagesで公開済み
- 記事はMarkdown（
.md）で作成し、ショートコードを適宜挿入
目的
- 記事品質と生産性を両立：繰り返し使う表現をショートコード化し、統一感と更新容易性を確保する
結果（この時点でできること）
- 以降のセクションで、組み込みショートコードの活用から自作までをスムーズに実施できる
注意
テーマに同名ショートコードが存在する場合、プロジェクト側が優先されます。競合時は命名や配置を見直してください。
🧩 基本の使い方（組み込みショートコード）
組み込みショートコードの使い方を、操作→目的→結果→注意で確認します。この記事の例はPaperModでもそのまま使えます。
YouTube動画を埋め込む
操作
- 記事内で
youtubeショートコードに動画IDを渡して埋め込みます。
目的
- YouTube動画をレスポンシブ対応で簡単に埋め込む。
結果（この時点でできること）
- 記事本文に動画プレイヤーが表示され、モバイルでも崩れにくい。
注意
ページ表示速度への影響を抑えるため、動画の数は最小限に。必要なら折りたたみ（details）と併用して視認性を保つ。
操作（例）
🖼️ 画像ショートコード（figure）
画像をキャプション付きで挿入する標準ショートコードです。
操作
figureショートコードにsrcとtitle（キャプション）などを渡します。
サンプル画像
目的
- 画像に説明文（キャプション）を付け、意味づけとアクセシビリティを強化する。
結果（この時点でできること）
- 表示画像の下にキャプションが付き、記事の文脈が明確になる。
補足
PaperModではoptimizedショートコードを用いると、WebP生成やレスポンシブ対応が可能です（テーマ拡張機能）。
🛠️ カスタムショートコードを作る
Hugoの真価は自作ショートコードにあります。共通パターンを部品化して保守性を高めましょう。
例：注意ボックスショートコード
操作（1. ファイルを作成）
layouts/shortcodes/alert.htmlを作成し、次のテンプレートを記述します。
注意： {{ .Inner }}
目的
- 記事内で繰り返し登場する注意書きを、統一デザインで簡単に挿入する。
結果（この時点でできること）
- 記事側で
<alert>を呼び出すだけで、デザインが統一された注意ボックスが表示される。
補足
{{ .Inner }}はショートコードの中身をそのまま出力する特別な変数です。
操作（2. 記事で使う）
注意：
ここに注意書きを入れます。
注意
複数の注意ボックスを使う場合は、見出しや文脈直下に置いて読み手の流れを阻害しないようにしましょう。
🔢 パラメータ付きショートコード
ショートコードにはパラメータを渡して、表示やスタイルを柔軟に制御できます。
例：色付きボックス
操作（1. ファイルを作成）
layouts/shortcodes/box.htmlを作成し、次のテンプレートを記述します。
<div style="background: {{ .Get `color` }}; padding: 1rem; border-radius: .5rem;">
{{ .Inner }}
</div>
目的
- 背景色など見た目をパラメータ化して、記事内の強調表現を統一する。
結果（この時点でできること）
- 記事側で任意の色を指定でき、可読性とデザインの一貫性が向上する。
操作（2. 記事で使う）
背景色を指定できます。
注意
パラメータ名のスペルミスや引用符の閉じ忘れに注意。{{ .Get "color" }}で取得できない場合は未定義の可能性があります。
📁 ショートコードの配置場所まとめ
プロジェクト内の配置規則と優先順位を確認します。
操作
layouts/shortcodes/ディレクトリにショートコードの.htmlを配置します。
# プロジェクト構成例
.
├─ layouts/
│ └─ shortcodes/
│ ├─ alert.html
│ └─ box.html
└─ content/
└─ posts/
目的
- プロジェクト固有のショートコードを管理し、テーマと競合しないようにする。
結果（この時点でできること）
- テーマ側に同名ショートコードがあっても、プロジェクト側が優先され、意図した出力を得られる。
注意
テーマアップデートで同名が追加される場合があるため、命名・役割の重複に定期的に注意してください。
🚀 実践：PaperModでよく使うショートコード
PaperModユーザー向けに、使用頻度の高いショートコードを紹介します。
optimized（画像最適化）
操作
- 画像を最適化して挿入します（WebP化とレスポンシブ対応）。
目的
- 画像の読み込み最適化（容量削減・表示品質向上）を行い、Core Web Vitalsを改善する。
結果（この時点でできること）
- 表示品質と速度の両立が可能になり、モバイル表示での安定性が向上する。
注意
画像の原本サイズ・圧縮率・altの品質に注意。altは画像の意味を正しく伝えるテキストにしてください。
details（折りたたみ）
操作
- 折りたたみセクションを挿入して、情報の視認性を保ちます。
Details
折りたたみ内容
目的
- 情報量の多い記事で、重要度の低い補足を整理し、読みやすさを維持する。
結果（この時点でできること）
- 初心者が必要な情報に集中でき、詳細は必要時のみ展開して確認できる。
補足
折りたたみの乱用は禁物。重要情報は本文で明示し、補助情報のみをdetailsへ。
✅ よくあるつまずき（チェックリスト）
- ショートコードのファイル名が
.htmlになっている -
layouts/shortcodes/に配置している（テーマ側ではなくプロジェクト側） - パラメータ名のスペルに誤りがない（例：
color） -
{{ .Inner }}と{{ .Get }}の役割を正しく使い分けている - テーマ側ショートコードと同名競合がない（または意図的に上書きしている）
- 画像の
altが意味を説明するテキストになっている（装飾的説明のみになっていない） - 大きな埋め込み（YouTube等）は件数を絞り、必要なら
detailsで折りたたんでいる - 見出し（h2）は絵文字＋目的が分かる文言で統一し、h3には絵文字を付けていない
- コードブロックの前に「目的」を1〜2文で明記している
- コードブロックの後に「結果」を1〜2文で明記している
- 必要に応じてコード直後に注意/補足を明示している（失敗例・代替手段）
-
toc: trueとtocopen: trueを設定し、目次の表示が意図通りになっている - Front matterの
title・description・slugが検索意図に合致している -
tagsが具体的（5〜8件）で、主要キーワードが含まれている - h2（主要セクション）に主要キーワード、h3（補助セクション）に補助キーワード（方式/失敗例/使い方）を含めている
📚 参考リンク
- Hugo 公式ドキュメント
- Shortcodes（概要・使い方）：https://gohugo.io/content-management/shortcodes/
- Custom Shortcodes（テンプレート作成）：https://gohugo.io/templates/shortcode-templates/
- PaperMod Docs
- テーマの機能と拡張：https://adityatelange.github.io/hugo-PaperMod/
注記
公式ドキュメントは随時更新されます。画面ラベルや一部の挙動が変わっている場合は、上記の最新情報を参照してください。
🔧 拡張案（次にやると良いこと）
- ショートコードにCSSを適用してデザイン統一
- 複雑なHTMLブロックをショートコード化して記事の可読性向上
- YouTube以外の埋め込み（X/Twitter、Slideshareなど）を自作ショートコード化
- 画像最適化パイプラインと連携したショートコードの作成
- 多言語サイト向けに i18n 対応ショートコードを作る
🎯 まとめ
- Hugoのショートコードは、記事の表現力と保守性を大幅に向上させます。
- 組み込みショートコードで手早く改善し、自作ショートコードで運用効率をさらに高めましょう。
- PaperMod環境でも相性が良く、画像最適化や折りたたみなどの活用でUXとSEOの両立が可能です。