OD Structured Data

OD Structured Data は、WordPress の投稿・固定ページ・著者・画像・サイト情報をもとに、Schema.org 準拠の JSON-LD を生成する WordPress プラグインです。

完成済み JSON-LD を手入力して保存するのではなく、WordPress がすでに持っている情報を標準 API で解決し、必要な上書き値だけを投稿ごとに補う設計です。初期リリースでは Article 系 Schema の管理、検証、プレビュー、フロントエンド出力に対応しています。

主な機能

• 設定画面で選択した投稿タイプに構造化データ設定を追加
• ブロックエディターの投稿設定パネルから投稿単位で有効化
• 新規コンテンツで構造化データをデフォルト有効化する設定
• 既存コンテンツの一括有効化
• Article と BlogPosting の切り替え
• 投稿タイトル、URL、公開日時、更新日時、著者、アイキャッチ画像、サイト名、サイト URL を自動取得
• 見出し、説明文、画像、著者名の上書き
• WordPress 標準のメディア選択 UI による画像上書き
• PHP で生成した JSON-LD の編集画面プレビュー
• PHP 側の検証結果を編集画面に表示
• フロントエンドの wp_head から JSON-LD を出力
• Article、WebPage、WebSite、Organization を含む @graph 出力
• Yoast SEO、Rank Math、All in One SEO との重複出力可能性の警告
• PHP フィルターによる対象投稿タイプ、Schema タイプ、生成データ、出力可否の拡張
• GitHub Releases を使ったプラグイン更新配信

対応範囲

初期リリースでは Article 系 Schema に絞っています。

対応 Schema:

• Article
• BlogPosting
• WebPage
• WebSite
• Organization

対応投稿タイプは初期状態では未選択です。設定 > OD Structured Data で投稿、固定ページ、公開カスタム投稿タイプから必要なものにチェックを入れると、対象の編集画面で構造化データ設定を利用できます。

対象投稿タイプは od_structured_data_post_types フィルターでも変更できます。

要件

プラグイン実行環境:

• WordPress 6.8 以上
• WordPress 7.0.2 まで検証済み
• PHP 7.4 以上

WordPress の利用可能な下限は 6.8 です。互換性確認では、現在の最新安定版である WordPress 7.0.2 と、6.8 系の最新パッチ版である WordPress 6.8.6 で npm test が通ることを確認しています。

開発環境:

• Node.js 20 以上
• npm 10 以上
• Composer 2
• Docker Desktop または @wordpress/env が利用できる Docker runtime

インストール

GitHub Release から od-structured-data.zip をダウンロードし、WordPress 管理画面の「プラグイン > 新規追加 > プラグインのアップロード」からインストールしてください。

このリポジトリを直接配置する場合は、プラグインディレクトリ名を od-structured-data にしてください。

composer install --no-dev --prefer-dist --optimize-autoloader

基本的な使い方

1. WordPress 管理画面で OD Structured Data を有効化します。
2. 設定 > OD Structured Data で、対応したい投稿タイプにチェックを入れて保存します。
3. 新しく作成する投稿で最初から有効化したい場合は、「新規コンテンツでは構造化データをデフォルトで有効化する」にチェックを入れて保存します。
4. 既存の投稿や固定ページもまとめて有効化したい場合は、同じ設定画面で「既存コンテンツを有効化」を実行します。
5. 対象投稿タイプのブロックエディターを開きます。
6. 投稿設定サイドバーの「構造化データ」パネルを開きます。
7. 必要に応じて Schema タイプ、見出し、説明文、画像、著者名を上書きします。
8. 検証結果と JSON-LD プレビューを確認します。
9. 投稿を保存すると、フロントエンドの wp_head に JSON-LD が出力されます。

詳しい使い方は docs/usage.md を参照してください。

保存されるデータ

投稿ごとの設定は _od_structured_data という投稿メタに保存されます。保存するのは完成済み JSON-LD ではなく、出力有効状態、Schema タイプ、上書き値、機能フラグだけです。

{
  "enabled": true,
  "schemaType": "BlogPosting",
  "overrides": {
    "headline": "",
    "description": "",
    "imageId": 0,
    "authorName": ""
  },
  "features": {
    "article": true,
    "faqFromBlocks": false
  }
}

REST API

編集画面の JSON-LD プレビューは、保存前の投稿メタ相当設定をサーバー側へ送り、PHP の実生成結果を表示します。

Endpoint:

POST /wp-json/od-structured-data/v1/preview

リクエストには対象投稿の postId と _od_structured_data 相当の settings を含めます。対象投稿を編集できないユーザーは利用できません。

詳細は docs/usage.md を参照してください。

フック

このプラグインは、対象投稿タイプ、許可 Schema タイプ、解決済み投稿データ、Article schema、JSON-LD graph、出力可否をフィルターで拡張できます。

主なフィルター:

• od_structured_data_post_types
• od_structured_data_allowed_article_types
• od_structured_data_post_settings
• od_structured_data_resolved_post_data
• od_structured_data_article_schema
• od_structured_data_graph
• od_structured_data_should_render

詳しい引数と利用例は docs/hooks.md を参照してください。

SEO プラグインとの関係

OD Structured Data は、他の SEO プラグインが出力する JSON-LD を勝手に削除・停止しません。Yoast SEO、Rank Math、All in One SEO が有効な場合は、編集画面に重複出力の可能性を警告します。

重複を避けたい場合は、投稿ごとの出力設定、または od_structured_data_should_render フィルターで出力可否を制御してください。

開発環境

npm install
composer install
npm run env:start

ローカル WordPress の URL は wp-env の出力を確認してください。

初期ログイン情報:

• Username: admin
• Password: password

開発コマンド

npm run env:start    # WordPress 環境を起動
npm run env:stop     # WordPress 環境を停止
npm run env:destroy  # WordPress コンテナと volume を削除
npm run env:logs     # wp-env のログを表示
npm run wp -- --info # WP-CLI を実行
npm test             # PHPUnit と smoke test を実行
npm run test:php     # PHP unit / integration test を実行
npm run test:smoke   # WordPress からプラグインを認識できるか確認

PHPUnit は wp-env に同梱された WordPress テストライブラリを使用します。先に npm run env:start で環境を起動してください。

互換性確認時は .wp-env.json の core を一時的に WordPress/WordPress#6.8.6 などへ切り替え、npm run env:start の後に npm test を実行してください。通常の開発では core を固定せず、wp-env の既定の最新安定版で確認します。

リリース

GitHub Releases を使って、WordPress 管理画面からプラグイン更新を配信します。

1. od-structured-data.php のプラグインヘッダーと OD_STRUCTURED_DATA_VERSION をリリースするバージョンに更新します。
2. 1.2.3 のような *.*.* 形式のタグを作成して push します。
3. GitHub Actions が Release を作成し、od-structured-data.zip を添付します。
4. WordPress 管理画面のプラグイン更新は、最新の GitHub Release を参照します。

ドキュメント

• 使い方と機能詳細
• フック一覧
• プラグイン設計・仕様

リポジトリ構成

.
├── assets/
│   ├── editor.css
│   └── editor.js
├── docs/
│   ├── README.md
│   ├── hooks.md
│   ├── plugin-design-spec.md
│   └── usage.md
├── includes/
│   ├── class-article-schema.php
│   ├── class-editor-assets.php
│   ├── class-graph-builder.php
│   ├── class-json-ld-renderer.php
│   ├── class-preview-rest-controller.php
│   ├── class-plugin.php
│   ├── class-plugin-settings.php
│   ├── class-post-meta-registrar.php
│   ├── class-post-resolver.php
│   └── ...
├── tests/
├── od-structured-data.php
├── package.json
└── README.md

ライセンス

GPL-2.0-or-later