ショートコード＆ブロック

記事本文に著者パネルを挿入する 2 つの方法（Gutenberg ブロックと [author_panel] ショートコード）の全属性・JSON-LD 出力・ネストブロック対応・REST API 経由のエンティティ取得までを解説します。

ブロックとショートコードは内部的に同じレンダラー（KAPM_Shortcode::render()）を共有しており、どちらで挿入しても HTML 出力と JSON-LD 出力は同一です。ブロックはキャメルケース属性（targetSchemaId）、ショートコードはスネークケース属性（target_schema_id）という表記差があるだけで、KAPM_Gutenberg::render_block() が内部で属性名を変換してから共通レンダラーへ渡しています。

Gutenberg ブロック

ブロック名: kapm/author-panel（カテゴリ widgets、アイコン id-alt）。ブロック追加メニューで「著者」「author」「Kashiwazaki」などで検索できます。

投稿・固定ページの編集画面で +（ブロック追加） ボタンをクリックし、検索欄に author や kashiwazaki を入力します。

Kashiwazaki SEO Author Panel Manager ブロックを選択して挿入します。挿入直後は「エンティティ未選択」のプレースホルダが表示されます。

右サイドバー（InspectorControls）の Person / Corporation / Organization パネルから、表示したいエンティティをチェックボックスで選択します。チェック直後に「表示ラベル」入力欄が現れます。

出力モード パネルで Standard / Custom を選びます。Custom 選択時は「紐付け先スキーマの @id」入力欄が追加表示されます。

ブロック属性リファレンス（全 6 属性）

includes/class-gutenberg.php の register_block_type() で定義されている 6 個の属性です。すべて string 型で、デフォルト値は空文字またはそれに準じる値になっています。

属性名（キャメル）	型	既定値	内容
`persons`	`string`	`''`	表示する Person エンティティ ID のカンマ区切りリスト（例: `"1,3,5"`）。
`corporations`	`string`	`''`	表示する Corporation エンティティ ID のカンマ区切りリスト。
`organizations`	`string`	`''`	表示する Organization エンティティ ID のカンマ区切りリスト。
`mode`	`string`	`'standard'`	JSON-LD 出力モード。`standard`（独立 `@graph` を本文内に出力）または `custom`（既存スキーマの `@id` に紐付けて `wp_head` に出力）。
`targetSchemaId`	`string`	`''`	Custom モードで紐付け先スキーマの `@id` を指定します。空のまま Custom モードを選んだ場合、Custom JSON-LD は出力されません（HTML パネルのみ表示）。
`labels`	`string`	`'{}'`	エンティティごとの表示ラベル（「執筆者」「監修者」等）を格納した JSON 文字列。キー形式は `person-{id}` / `corp-{id}` / `org-{id}`。JSON として不正な場合は空オブジェクトとして扱われます。

サイドバー UI の 4 パネル構成

assets/js/gutenberg-sidebar.js の InspectorControls では、以下の 4 つの PanelBody が配置されます。

パネル名	主な UI 要素	操作対象の属性
Person	登録済み Person の一覧をチェックボックスで表示。チェック中のエンティティごとに「表示ラベル」TextControl が展開（placeholder: 「例: 執筆者、監修者など」）。下部に「Person管理を開く」リンク。	`persons`, `labels`（`person-{id}` キー）
Corporation	登録済み Corporation のチェックボックス一覧とラベル入力欄（placeholder: 「例: 運営会社、スポンサーなど」）。	`corporations`, `labels`（`corp-{id}` キー）
Organization	登録済み Organization のチェックボックス一覧とラベル入力欄（placeholder: 「例: 運営メディア、発行元など」）。	`organizations`, `labels`（`org-{id}` キー）
出力モード	`RadioControl` で Standard / Custom の 2 択。Custom 選択時のみ `TextControl`「紐付け先スキーマの @id」が表示されます（placeholder: `https://example.com/#article`）。	`mode`, `targetSchemaId`

REST API 経由のエンティティ取得

サイドバーに並ぶチェックボックス一覧は、編集画面初期化時に fetch() で /wp-json/kapm/v1/persons／corporations／organizations の 3 エンドポイントから全件取得しています。X-WP-Nonce ヘッダーに kapmData.nonce（wp_rest nonce）を付与し、権限は current_user_can('edit_posts')。詳細は REST API 仕様を参照してください。

ブロックのプレビュー表示

エンティティが 1 件以上選択されている場合、ブロック本体にプレビュー枠が表示されます。Person は 👤、Corporation は 🏢、Organization は 🏛 のアイコン付きで登録名が並び、下部に現在の Mode と（Custom 時は）Target が表示されます。選択ゼロの場合は WordPress 標準の Placeholder コンポーネントで「右サイドバーから選択してください」と表示されます。

ショートコード `[author_panel]`

クラシックエディタで記事本文にショートコードを書く場合や、ウィジェット・テーマテンプレートから do_shortcode() で呼び出す場合はショートコードを利用します。

Custom モードは投稿本文 (post_content) のみが対象

preparse_custom_mode() は template_redirect で現在投稿の $post->post_content を直接パースして Custom モードを検出します。そのため、ウィジェットエリア・テーマテンプレート (header.php / footer.php / sidebar.php 等)・ブロックパターン・フッター CPT からの do_shortcode() 呼び出しは Custom モードの JSON-LD には含まれません（HTML パネル自体は正常に出力されます）。テンプレートやウィジェットで著者パネルを出したい場合は、Standard モードのみ利用可能と考えてください。

最小構文:

[author_panel persons="1,2" corporations="3"]

Custom モードで Yoast SEO などが出力した記事スキーマに紐付ける例:

[author_panel persons="1" corporations="3" mode="custom" target_schema_id="https://example.com/post/#article"]

ショートコード属性リファレンス（全 6 属性）

ブロックと完全対応していますが、属性名がスネークケースに変わる点と target_schema_id のアンダースコア表記に注意してください。

属性名	既定値	内容・注意点
`persons`	`''`	Person ID のカンマ区切りリスト。`parse_ids()` で `absint()` + `array_filter` 処理されるため、0 や不正値（文字列、負数）は自動的に捨てられます。
`corporations`	`''`	Corporation ID のカンマ区切りリスト。処理ルールは `persons` と同じ。
`organizations`	`''`	Organization ID のカンマ区切りリスト。処理ルールは同上。
`mode`	`'standard'`	JSON-LD 出力モード。`standard` または `custom`。それ以外の値は Standard として扱われます。
`target_schema_id`	`''`	Custom モードでの紐付け先 `@id`。Custom モードでこれが空だと Custom 側の JSON-LD は一切出力されません（HTML パネルのみ表示）。
`labels`	`'{}'`	表示ラベルの JSON 文字列。`json_decode()` が失敗した場合は空配列扱いになり、ラベルは表示されません。

すべての ID が空 or 無効のとき

persons / corporations / organizations のすべてが空文字、または parse_ids() 後にすべて空配列になった場合、ショートコードは空文字 '' を返します（HTML にも JSON-LD にも何も出力されません）。指定した ID のエンティティが DB から見つからなかった場合も同様です。

JSON-LD 出力（Standard モード）

Standard モードでは、HTML パネルの直後に <script type="application/ld+json"> で独立した JSON-LD が埋め込まれます。出力される構造は @context + @graph で、@graph に Person / Corporation / Organization の各ノードが並びます。

例: Person 1 人 + Corporation 1 社を挿入した場合の出力（整形済み）:

<!-- Kashiwazaki SEO Author Panel Manager - Standard Mode JSON-LD -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Person",
      "@id": "https://example.com/profile/#person-1",
      "name": "柏崎 剛",
      "alternateName": "Tsuyoshi Kashiwazaki",
      "jobTitle": "SEO エンジニア",
      "description": "〜〜〜",
      "image": {
        "@type": "ImageObject",
        "url": "https://example.com/avatar.jpg"
      },
      "url": "https://example.com/profile/",
      "sameAs": [
        "https://x.com/username",
        "https://github.com/username"
      ]
    },
    {
      "@type": "Corporation",
      "@id": "https://example.com/company/#corporation-3",
      "name": "株式会社サンプル",
      "alternateName": "Sample Corporation",
      "description": "〜〜〜",
      "url": "https://example.com/company/",
      "logo": {
        "@type": "ImageObject",
        "url": "https://example.com/logo.png"
      },
      "sameAs": ["https://x.com/sample_corp"]
    }
  ]
}
</script>
<!-- / Kashiwazaki SEO Author Panel Manager -->

@id のフォールバック

各エンティティの @id は {エンティティの url}#person-{id} / #corporation-{id} / #organization-{id} の形で生成されます。エンティティの url が空の場合、ベース URL は home_url('/')（サイトのホーム URL）にフォールバックします。

省略プロパティ

未入力のフィールドに対応する JSON プロパティは出力されません（'' や null ではなくキー自体が省略されます）。例えば Person で英語名が未入力なら alternateName は存在せず、sameAs が 1 件も有効 URL を含まなければ sameAs プロパティそのものが出ません。

JSON-LD 出力（Custom モード）

Custom モードは、他プラグイン（Yoast SEO、Rank Math、SEO SIMPLE PACK 等）が <head> 内に出力している Article / NewsArticle / WebPage などの既存スキーマへ、本プラグインのエンティティを プロパティとして紐付けるための出力方式です。

Custom モードの動作フロー

template_redirect で preparse_custom_mode() が走り、is_singular() が真のときのみ（個別投稿・固定ページ・個別カスタム投稿のみ）、現在の投稿の post_content をパースします。

parse_blocks() でブロック配列を取得し、scan_blocks_for_custom() が再帰的に走査。kapm/author-panel ブロックを検出するたびに、mode === 'custom' かつ targetSchemaId が非空であれば対象としてメモリに保持します。Group / Columns / Row など innerBlocks を持つコンテナ内のネストブロックも検出されます。

同じ preparse_custom_mode() がショートコード形式 [author_panel ... mode="custom"] を get_shortcode_regex() で検出し、shortcode_parse_atts() でパースして同様にメモリに保持します。

wp_head（優先度 99、</head> 直前に近い）で output_custom_json_ld() が、収集した全 Custom データを 1 つずつ <script type="application/ld+json"> として出力します。

アーカイブ・ホームでは Custom モードは動作しません

preparse_custom_mode() は is_singular() でガードされているため、カテゴリーアーカイブ・タグアーカイブ・検索結果・ホームページでは Custom 側の JSON-LD は出力されません。アーカイブ系で著者パネルを出したい場合は Standard モードを使用してください。HTML パネル自体（ショートコード本体の出力）はこの制約の対象外です。

Custom モードの JSON-LD 出力例

例: Yoast SEO が Article を @id: "https://example.com/post-slug/#article" で出力しているページに、Person 1（role=Author）と Corporation 3（role=Publisher）を紐付けた場合の Custom 側出力:

<!-- Kashiwazaki SEO Author Panel Manager - Custom Mode JSON-LD -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Person",
      "@id": "https://example.com/profile/#person-1",
      "name": "柏崎 剛",
      "url": "https://example.com/profile/",
      "sameAs": ["https://x.com/username"]
    },
    {
      "@type": "Corporation",
      "@id": "https://example.com/company/#corporation-3",
      "name": "株式会社サンプル",
      "url": "https://example.com/company/"
    },
    {
      "@id": "https://example.com/post-slug/#article",
      "author":    { "@id": "https://example.com/profile/#person-1" },
      "publisher": { "@id": "https://example.com/company/#corporation-3" }
    }
  ]
}
</script>
<!-- / Kashiwazaki SEO Author Panel Manager -->

最後のノードは @id だけの「参照ノード」で、ブロック側で指定した target_schema_id がそのまま入ります。このノードに author / publisher などのプロパティが @id 参照として追加され、他プラグインの Article ノードと同一 @id であれば Google 等のパーサ側でマージ解釈されます。

role_to_property() による分岐

上記例の author / publisher プロパティ名は、各エンティティの role フィールド値を role_to_property() で変換した結果です。全 9 分岐のマッピングはエンティティ管理ページの Role 変換表を参照してください。

同じ role に複数エンティティが紐付いた場合（例: 共著で Person が 2 人、どちらも Author）、2 人目以降は配列形式にまとめられ、"author": [ {"@id": "..."}, {"@id": "..."} ] の形で出力されます。

Standard と Custom は併用可能

1 記事内で複数のブロック／ショートコードを挿入し、一方を Standard、もう一方を Custom にすることもできます。Standard は本文内、Custom は <head> 内と出力先が分かれているため衝突しません。

フロントエンド HTML 出力

HTML はルート要素 .kapm-author-panel の中に、エンティティごとのカード .kapm-author-card を flex で並べる構造です。各カードにはエンティティ種別（.kapm-person / .kapm-corporation / .kapm-organization）と panel_style（.kapm-style-default ほか）の 2 つのクラスが付きます。

Person のカード内では、名前が URL にリンクされる際に rel="author" 属性が付きます（Corporation / Organization のリンクには付きません）。これは Person 特有の扱いで、検索エンジンに対して「この記事の著者リンク」であることを伝える役割があります。

CSS の読み込み条件

フロントエンド CSS（public/css/panel-style.css、実測 4,629 バイト）は、ショートコードが render() される時点で wp_enqueue_style() されます。著者パネルが挿入されていないページでは CSS は読み込まれません。フロントエンド側で独自 JavaScript は一切使用しません（Core Web Vitals に追加の JS 評価コストを発生させません）。

sameAs アイコンマッピング全 44 ドメイン

エンティティの sameAs URL は、フロント側で Dashicons アイコン付きリンクとして表示されます。URL のホスト名から自動的にサービスを判定し、以下 44 パターンのいずれかにマッチすれば対応アイコン、マッチしなければ dashicons-admin-site（汎用 Web サイトアイコン）が使われます。

マッチロジック: wp_parse_url($url, PHP_URL_HOST) で取得したホスト名から www. を取り除き、マップキーと完全一致するか、末尾ドット付きキー（例: amazon.）で前方一致するかを判定します。

SNS・コミュニケーション系

ドメインパターン	Dashicons クラス	サービス
`x.com`	`dashicons-twitter-alt`	X (旧 Twitter)
`twitter.com`	`dashicons-twitter-alt`	Twitter (旧ドメイン)
`facebook.com`	`dashicons-facebook-alt`	Facebook
`instagram.com`	`dashicons-camera`	Instagram
`linkedin.com`	`dashicons-businessperson`	LinkedIn
`threads.net`	`dashicons-format-status`	Threads
`bsky.app`	`dashicons-share`	Bluesky
`mastodon.`（前方一致）	`dashicons-share`	Mastodon (インスタンス全般)
`tumblr.com`	`dashicons-share`	Tumblr
`reddit.com`	`dashicons-format-chat`	Reddit
`pinterest.`（前方一致）	`dashicons-admin-post`	Pinterest (地域 TLD 全般)
`tiktok.com`	`dashicons-format-video`	TikTok
`telegram.org`	`dashicons-email-alt`	Telegram
`t.me`	`dashicons-email-alt`	Telegram 短縮
`whatsapp.com`	`dashicons-phone`	WhatsApp
`wa.me`	`dashicons-phone`	WhatsApp 短縮

動画・音声・画像系

ドメインパターン	Dashicons クラス	サービス
`youtube.com`	`dashicons-video-alt3`	YouTube
`youtu.be`	`dashicons-video-alt3`	YouTube 短縮
`vimeo.com`	`dashicons-video-alt2`	Vimeo
`twitch.tv`	`dashicons-video-alt`	Twitch
`spotify.com`	`dashicons-format-audio`	Spotify
`soundcloud.com`	`dashicons-format-audio`	SoundCloud
`flickr.com`	`dashicons-camera`	Flickr

開発者・技術系

ドメインパターン	Dashicons クラス	サービス
`github.com`	`dashicons-editor-code`	GitHub
`gitlab.com`	`dashicons-editor-code`	GitLab
`bitbucket.org`	`dashicons-editor-code`	Bitbucket
`stackoverflow.com`	`dashicons-editor-help`	Stack Overflow
`qiita.com`	`dashicons-lightbulb`	Qiita
`zenn.dev`	`dashicons-lightbulb`	Zenn

学術・研究系（E-E-A-T の文脈で重要）

ドメインパターン	Dashicons クラス	サービス
`scholar.google.`（前方一致）	`dashicons-welcome-learn-more`	Google Scholar (TLD 全般)
`researchgate.net`	`dashicons-welcome-learn-more`	ResearchGate
`orcid.org`	`dashicons-welcome-learn-more`	ORCID
`osf.io`	`dashicons-welcome-learn-more`	OSF (Open Science Framework)
`ideas.repec.org`	`dashicons-welcome-learn-more`	RePEc (経済学)

ブログ・コンテンツ・その他

ドメインパターン	Dashicons クラス	サービス
`medium.com`	`dashicons-edit`	Medium
`note.com`	`dashicons-welcome-write-blog`	note
`note.mu`	`dashicons-welcome-write-blog`	note (旧ドメイン)
`wordpress.org`	`dashicons-wordpress`	WordPress.org
`wordpress.com`	`dashicons-wordpress`	WordPress.com
`wikipedia.org`	`dashicons-book`	Wikipedia
`goodreads.com`	`dashicons-book-alt`	Goodreads
`amazon.`（前方一致）	`dashicons-cart`	Amazon (地域 TLD 全般。著者ページ等)
`patreon.com`	`dashicons-money-alt`	Patreon
`gravatar.com`	`dashicons-admin-users`	Gravatar
上記に該当しないドメイン	`dashicons-admin-site`	汎用 Web サイト（フォールバック）

入力値の検証

sameAs フィールドに入力した 1 行が filter_var($line, FILTER_VALIDATE_URL) を通らなかった場合、その行は JSON-LD の sameAs 配列にもアイコン表示にも使われません。http:// / https:// から始まる完全な URL を入力してください。

ショートコード / ブロックの処理フローと JSON-LD 出力 — ショートコード / ブロックの処理フローと Standard / Custom JSON-LD の出力先