親テーマ・子テーマの関係

WordPress では対象ファイルの種類によって「親優先」「子優先」「両方読み込み」が変わります。混乱しがちなので一覧化しておきます。

テンプレートファイル(*.php / template-parts/)

子 → 親 の順で解決。子テーマに同名ファイルがあればそちらが使われる(例: front-page.php / single-column.php / template-parts/card/column-card.php 等)。差し替えたい時は同じパス・同じファイル名で子に置く。

関数定義(functions.php)

両方とも実行される(子 → 親 の順)。テンプレートと逆なので注意。親側のヘルパー関数は function_exists() でラップしてあるので、子テーマで先に同名関数を定義すれば上書き可能。

スタイルシート(style.css)

親 → 子 の順で enqueue。後ロードの子が CSS カスケードで優先される。子で同セレクタを書けばそのまま上書きできる。

CSS カスタムプロパティ(デザイントークン)

親が :root で全トークンを定義済み。子は src/scss/_overrides.scss で :root を再宣言した値だけ上書きすれば、配色・余白などが案件別に切り替わる(全部書き直す必要なし)。

独自ブロック

親で register_block_type() 登録済み。同名ブロックの再登録は不可。子で新規ブロックを追加する場合は別の名前空間(例: child-slug/your-block)で。

CPT・タクソノミー・ACF

CPT・タクソノミー・フィールドグループとも ACF の管理画面側で作成・編集する(DB に登録されるため、テーマ切替で消えない)。本テーマは Local JSON 連携を組み込み済みで、ACF 管理画面で保存すると acf-json/ にファイル書き出しされる。書き込み先は inc/acf.php 冒頭の MDT_ACF_DEV_SAVE_ALL_TO_PARENT 定数で切替。デフォルトは false(各案件の開発・運用フェーズ)で、何を保存しても子 acf-json/ に書き込まれ、親には一切書き込まれない。親テーマ開発の時のみ true にすると、全 JSON を親 acf-json/ に保存できる。親の共通基盤を更新したい場合は子→親へ手動でファイルを移動する。load は常に 親 → 子 の順(同一 key は子が後勝ち)。
⚠ 注意: 親テーマは将来アップデート・差し替えされる可能性があるため、親 acf-json/ に保存した JSON は親テーマ差し替え時に消える。親テーマ開発で true にしているときに案件独自の CPT・フィールドまで親に保存してしまうと、アップデートで失う恐れがある。false に戻す前に、共通基盤として残すもの以外は子テーマへ移しておくこと。

開発フロー

1. 子テーマ mdtemplate-child を案件名のディレクトリにコピー(例: mdtemplate-projectA)
2. コピー先の style.css ヘッダーの Theme Name を案件名に書き換え(Template: mdtemplate-base は維持)
3. 子テーマ内で npm install → npm run build
4. 管理画面 → 外観 → テーマ で子テーマを有効化
5. 新規環境では管理画面の ACF → ACF同期 で、親テーマ acf-json/ の CPT(column / faq / supervisor / editor)・タクソノミー・フィールドグループを取り込む
6. CF7 でお問い合わせフォームを作成し、固定ページに page-contact.php テンプレートを割当て
7. npm run watch で SCSS を監視しながら子テーマ側で本実装を進める
8. 配色変更は子テーマの src/scss/_overrides.scss で CSS 変数を上書き

補足

• ACF Pro は不要 ― CPT・フィールドグループとも無料版で作成可能(ブロックも独自実装なので Pro 機能に依存しない)
• 標準の「投稿(post)」は管理画面 UI から非表示化済み。記事は column を使う
• 日本語タイトルから生成される URL スラッグは自動で {post_type}-{ID} 形式(例: column-12)に置換される
• CF7 のプラグイン側 CSS は無効化済み。装飾は親テーマの _form.scss 側で当てている
• reCAPTCHA v3: 親テーマ CSS で右下のフローティングバッジを非表示(.grecaptcha-badge { visibility: hidden; })にしている。Google の規約により、代わりにフォーム送信ボタン直前に「protected by reCAPTCHA」帰属表記を必ず表示すること(クラスは .c-recaptcha-notice、CF7 ショートコード本文で記述)。CF7 → インテグレーションで Site key / Secret key が未登録の場合、CF7 フォームがあるページで管理者ログイン中ユーザーにのみ右下に「⚠ reCAPTCHA が未設定です」アラートを出す(訪問者には表示されない)。検出ロジックは inc/cf7.php
• 独自ブロック: マーカー(インライン書式) / キャプションボックス / FAQ(親+子ブロック) / ブログカード(あわせて読みたい・内部リンク専用)
• テンプレートやテンプレートパーツを子テーマで上書きする場合は、親と同じパス・同じファイル名で配置する
• ヘルパー関数: mdt_breadcrumb() / mdt_pagination() / mdt_post_meta()
• ACF Local JSON モード切替: inc/acf.php の MDT_ACF_DEV_SAVE_ALL_TO_PARENT はデフォルト false。保存先がすべて子テーマ acf-json/ に固定される(各案件の開発・運用フェーズ)。親テーマ開発の時のみ true にして親の共通基盤を更新する。true のまま放置すると案件側の CPT・フィールドも親に書き込まれ、親テーマ差し替え時に消えるリスクあり

親テーマの更新(GitHub Releases)

親テーマ mdtemplate-base は GitHub の private repo で管理し、v* タグを push すると Actions が build 済み zip(mdtemplate-base.zip)を Release に添付する。各案件サイトの wp-config.php に repo URL と Personal Access Token を定数で定義しておけば、管理画面「テーマ → 更新」から WP 標準の更新フローで適用できる。

案件サイトへの組み込み

本番(または共有ステージング)サーバーの wp-config.php に以下を追記する(/* That's all, stop editing! */ の上)。

define( 'MDT_GH_REPO',  'https://github.com/<owner>/mdtemplate-base/' );
define( 'MDT_GH_TOKEN', 'github_pat_xxxxxxxx...' );

MDT_GH_REPO と MDT_GH_TOKEN の両方が定義されているときだけ inc/update.php が動く。片方でも欠ければ静かに無視されるので、ローカル開発環境では未定義のままで構わない。

PAT 運用のポイント

• PAT は 1 個を全案件で使い回せる。mdtemplate-base は全案件共通の親テーマ(repo は 1 つだけ)なので、すべての案件サイトの wp-config.php に同じ値を貼ればよい。
• wp-config.php への追記作業は各案件サーバーで毎回必要。WordPress の仕様上ここは自動化できないので、新規案件構築のチェックリストに「親テーマ更新用定数を追記」を入れておく。
• 子テーマには設定不要。PUC は親テーマ mdtemplate-base のみを監視しているので、子テーマ側の操作は一切発生しない(子テーマ自体を GitHub で更新通知したくなった場合は別の仕組みを足す)。
• fine-grained PAT を発行し、権限は Contents: Read-only、対象 repo を 1 つに絞る。期限は 1 年程度の有限にする(無期限 PAT は非推奨)。
• 期限切れや Regenerate 時は全案件の wp-config.php を順に差し替える運用になる。期限管理を 1 本に揃えるためにも PAT は共通 1 個で運用するのが現実的。

親テーマのリリース手順(親テーマ開発者向け)

1. style.css の Version: を上げる(例 1.0.0 → 1.1.0)
2. git add -A → git commit -m "Release v1.1.0"
3. git tag v1.1.0 → git push origin main --tags
4. Actions が自動で build → zip → Release 作成 → mdtemplate-base.zip 添付までを実行
5. 各案件サイトは管理画面「外観 → テーマ → 更新を確認」で新版が通知される

⚠ tag の数字(v1.1.0 の 1.1.0)と style.css の Version: の数字は必ず一致させること。一致しないと Actions の検証ステップで fail する。

仕組みの詳細(inc/update.php の挙動、Actions zip 生成、ACF JSON 上書きの注意点、リポジトリ移管時の手順)は repo の README.md 「親テーマ更新フロー」セクション参照。