WordPressショートコードの基本：記事内でフォームや一覧を呼び出す書き方
WordPressのショートコードは、記事本文に [contact-form] のような短い記法を書くだけで、フォーム、商品一覧、目次、ボタン、ギャラリーなどの機能を呼び出す仕組みです。
PHPを書けない編集者でも使える一方で、開発者側は add_shortcode() で「この記号が来たら何を表示するか」を登録できます。実務では、固定ページに問い合わせフォームを置く、キャンペーン用のCTAを差し込む、同じ案内枠を複数記事で使い回す、といった場面でよく使います。
この記事で分かることは次の3つです。
- ショートコードが何をしているのか
- 記事や固定ページでどう書くのか
- 自作・運用時にどこでつまずきやすいのか
対象は、WordPressで記事編集や簡単なテーマ調整をする初心者から実務初級者です。コード例はWordPress 6.x系の一般的な環境を前提にし、公式ドキュメントのShortcode APIをもとに整理します。
ショートコードは「本文から機能を呼ぶ合図」
ショートコードの本質は、本文中の短い文字列を、WordPressが表示時に別のHTMLや処理結果へ置き換えることです。
たとえば、記事本文に次のように書きます。
[contact-form]
WordPressやプラグイン側に contact-form というショートコードが登録されていれば、公開ページでは問い合わせフォームのHTMLに置き換わります。登録されていなければ、多くの場合はただの文字列として残ります。
ここがポイント: ショートコードは「記事にPHPを書く仕組み」ではなく、「登録済みの機能を本文から呼び出す合図」です。
この違いは実務で重要です。編集者は短い記法を入力するだけで済み、フォームのHTMLや複雑な処理はプラグインやテーマ側に閉じ込められます。記事本文を触る人と、機能を作る人の役割を分けられるのがショートコードの強みです。
基本の書き方：属性つきと囲み型を押さえる
ショートコードは、単に呼び出すだけでなく、属性を渡したり、本文の一部を囲んだりできます。
何も指定しない基本形
もっとも単純な形は、角括弧で名前を囲むだけです。
[latest_posts]
たとえば「最新記事一覧を3件表示する」処理が latest_posts として登録されていれば、この位置に一覧が表示されます。
属性で表示内容を変える
属性を使うと、同じショートコードでも表示条件を変えられます。
[latest_posts count="5" category="news"]
この例では、count に件数、category に対象カテゴリを渡しています。実際にどの属性が使えるかは、プラグインやテーマが用意した仕様によります。
入力例と出力のイメージは次の通りです。
入力:
[latest_posts count="3"]
出力例:
<ul class="latest-posts">
<li>記事タイトルA</li>
<li>記事タイトルB</li>
<li>記事タイトルC</li>
</ul>
WordPressのShortcode APIでは、属性名は小文字として扱われます。Count="3" のように大文字混じりで書くより、count="3" のように小文字でそろえる方が安全です。
囲み型で中身を渡す
ショートコードには、開始タグと終了タグで本文を囲む形もあります。
[notice type="warning"]
メンテナンス中は一部機能が利用できません。
[/notice]
この形では、囲まれた文章がショートコード側に渡されます。注意枠、ボタンリンク、注釈ボックスなど、本文の一部を装飾したいときに向いています。
記事編集画面では「ショートコードブロック」を使う
ブロックエディターでは、ショートコード専用のブロックを使うと入力位置が分かりやすくなります。
WordPressのブロックエディターには「ショートコード」ブロックがあります。そこに やプラグイン指定のショートコードを入力すると、公開ページで処理されます。
実務では、次のような使い分けが分かりやすいです。
- 普通の本文中に短く差し込む: 段落内に直接書く
- 1つの機能として独立して置く: ショートコードブロックを使う
- HTMLと混ぜて細かく調整する: カスタムHTMLブロックやテンプレート側で扱う
ただし、ショートコードの見た目や出力内容は、ブロック側ではなく登録元のプラグインやテーマに依存します。編集画面で見えている文字列と、公開ページの表示が違うことは珍しくありません。確認はプレビューだけで済ませず、公開ページに近い表示環境でも見るのが安全です。
自作する最小例：add_shortcodeで登録する
自分でショートコードを作る場合は、PHP側で add_shortcode() を使って名前と処理を登録します。
最小例は次の形です。テーマの functions.php に直接書くこともできますが、実務では小さな独自プラグインに分ける方が、テーマ変更時に機能が消えにくくなります。
<?php
// [hello_box] と書くと案内ボックスを表示する
function my_hello_box_shortcode() {
return '<div class="hello-box">お問い合わせはフォームからお願いします。</div>';
}
add_shortcode( 'hello_box', 'my_hello_box_shortcode' );
記事本文には次のように書きます。
[hello_box]
公開ページでは、次のHTMLが差し込まれるイメージです。
<div class="hello-box">お問い合わせはフォームからお願いします。</div>
ここで大事なのは、ショートコードの関数では echo ではなく return で文字列を返すことです。WordPress公式ドキュメントでも、ショートコードハンドラーの戻り値が本文中のショートコード位置に挿入される、と説明されています。
echo で出力すると、ページ内の意図しない場所に表示されたり、他の出力と順序がずれたりします。
属性を受け取る実務向けサンプル
固定文だけではなく、属性を受け取れるようにすると、同じショートコードを複数の場面で使い回せます。
たとえば、ボタンの文言とリンク先を変えられるショートコードを作ります。
<?php
function my_cta_button_shortcode( $atts ) {
$atts = shortcode_atts(
array(
'label' => '詳しく見る',
'url' => '/',
),
$atts
);
$label = esc_html( $atts['label'] );
$url = esc_url( $atts['url'] );
return '<p><a class="cta-button" href="' . $url . '">' . $label . '</a></p>';
}
add_shortcode( 'cta_button', 'my_cta_button_shortcode' );
記事側ではこう書けます。
[cta_button label="資料をダウンロード" url="/download/"]
出力例は次のようになります。
<p><a class="cta-button" href="/download/">資料をダウンロード</a></p>
この例で使っている shortcode_atts() は、未指定の属性に初期値を入れ、想定していない属性を整理するための関数です。label が省略されても「詳しく見る」が入り、url が省略されても / が使われます。
また、esc_html() と esc_url() で出力前にエスケープしています。記事編集者が入力する値でも、HTMLとしてそのまま出すと表示崩れやセキュリティ上の問題につながります。属性を受け取るショートコードでは、出力時のエスケープを必ず入れると考えてください。
よくある失敗と直し方
ショートコードでつまずく原因は、書き方の小さな違いか、登録元の機能が読み込まれていないことが多いです。
公開ページに [sample] がそのまま出る
ショートコード名が登録されていない可能性があります。
確認するポイントは次の通りです。
- 対象プラグインが有効化されているか
- ショートコード名のスペルが合っているか
- テーマ変更で
functions.phpの登録処理が消えていないか - 固定ページ、投稿、ウィジェットなど、使っている場所でショートコードが処理されるか
特に、以前は表示されていたのに急に文字列のまま出る場合は、プラグイン停止やテーマ変更を疑うと切り分けが早くなります。
属性が効かない
属性名の間違い、引用符の崩れ、プラグイン側がその属性に対応していない、という3つを確認します。
NG例です。
[cta_button Label="資料請求" link="/download/"]
改善例です。
[cta_button label="資料請求" url="/download/"]
WordPress側では属性名が小文字化されますが、そもそもショートコード側が url を期待しているのに link と書いても反映されません。プラグイン配布元の説明にある属性名をそのまま使うのが基本です。
囲み型の中で別のショートコードが動かない
囲み型ショートコードの中に別のショートコードを書いた場合、外側の処理が do_shortcode() を呼んでいないと内側が展開されないことがあります。
[box]
[cta_button label="申し込む" url="/apply/"]
[/box]
このような入れ子を許可したい場合、開発側では囲まれた内容に do_shortcode() をかける必要があります。ただし、何でも再帰的に処理すればよいわけではありません。ユーザー入力を含むHTMLを扱う場合は、許可するタグやエスケープ方針も一緒に決める必要があります。
ショートコード、ブロック、テンプレートの使い分け
現在のWordPressではブロックエディターが中心ですが、ショートコードはまだ実務で使われます。大事なのは、どれか一つに寄せることではなく、編集者が触る範囲と保守する範囲を分けることです。
| 方法 | 向いている場面 | 注意点 |
|---|---|---|
| ショートコード | フォーム、CTA、一覧などを記事内で呼び出す | 登録元のプラグインやテーマに依存する |
| ブロック | 編集画面で見た目を確認しながら配置する | 独自機能を作るにはブロック開発の知識が必要 |
| テンプレート | サイト全体で同じ位置に機能を出す | 編集者が記事ごとに出し分けにくい |
| カスタムフィールド | 入力項目を構造化して管理する | 表示側の実装が別途必要 |
ショートコードが特に向いているのは、「本文の好きな位置に、登録済みの小さな機能を置きたい」場面です。
一方で、全ページ共通のヘッダー下にバナーを出す、記事テンプレートの末尾に毎回同じ関連記事を出す、といった用途ならテンプレート側で管理した方が安定します。編集画面で視覚的に並べ替えたい要素なら、ブロック化を検討する価値があります。
運用前に確認したいチェックリスト
ショートコードは便利ですが、本文に記法が残るため、後から消すときの影響も考えておく必要があります。
公開前に、少なくとも次の点を確認してください。
- ショートコード名は短く、他のプラグインと衝突しにくいか
- 属性名は小文字で統一しているか
- 出力HTMLは
returnで返しているか - 属性や囲み内容を出力する前にエスケープしているか
- プラグイン停止時に本文へ記号だけが残っても問題ないか
- テーマ変更後も必要な機能なら、独自プラグイン側に置いているか
- 編集者向けに使える属性と入力例を残しているか
見落とされやすいのは、最後の「編集者向けの入力例」です。ショートコードは見た目が短い分、数か月後に見ると type="primary" や count="5" が何を意味するのか分からなくなりがちです。社内メモや管理画面の説明欄に、使える属性と例を残しておくと運用が崩れにくくなります。
まずは「呼び出すだけ」の用途から始める
WordPressのショートコードは、記事本文から機能を呼び出すための軽い仕組みです。問い合わせフォーム、CTA、記事一覧、注意枠のように、編集者が置き場所を選びたい部品と相性があります。
ただし、サイト全体の共通表示や、見た目を編集画面で細かく調整したい部品までショートコードで抱え込むと、後から管理しにくくなります。
最初に見るべき判断軸はシンプルです。
- 記事ごとに置き場所を変えたいなら、ショートコード
- 編集画面で見た目も操作したいなら、ブロック
- サイト全体で同じ位置に出したいなら、テンプレート
この3つを分けて考えるだけで、ショートコードを「便利だが残り続ける本文記法」として扱えるようになります。次に自作するなら、まずは固定文を返す小さなショートコードから始め、属性、エスケープ、入れ子処理の順に広げるのが実務では安全です。