acms-theme-development
/acms-theme-development
a-blog cms(acms)のテーマを作る・継承する・ブログに割り当てる・構成を直すときの手順と判断基準。 テンプレートの探索順(子テーマ名と親テーマ名をつないだディレクトリ名による多段継承と、system へのフォールバック)、template.yaml のキー、 カテゴリー別・エントリー別テンプレートの置き方、テーマセットによる割り当て、ファイル名の先頭 _ と直接表示の禁止、 アップデートで上書きされる場所、acms.js と管理用 CSS の読み込み、テンプレート内のパスの書き換え、 表示に使われているテンプレートの調べ方(デバッグモード)、大規模サイトの設計と運用(子ブログとカテゴリーの使い分け、 下の階層のブログとの共有、開発環境から本番環境への設定の移行、ページ・モジュール・テンプレートのキャッシュ、ベンチマークモード)を扱う。 「新しいテーマを作って」「子ブログ用のテーマを分けたい」「このページのテンプレートはどれ?」 「system のテンプレートを直したい」「画像や CSS のパスが合わない」「acms.js をログイン時だけ読み込みたい」 「子ブログとカテゴリーのどちらにすべき?」「開発環境の設定を本番に反映したい」「表示が重い」と頼まれたときに使う。 a-blog cms theme, child theme, template.yaml, theme
- Author
- appleple ↗
- Repository
- acms-agent-skills ↗
- Licence
- MIT
- Last repository change
- 12.11.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 0
- HTML comments
- 1
- URLs in SKILL.md
- 6
No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
a-blog cms(acms)のテーマを作る・継承する・ブログに割り当てる・構成を直すときの手順と判断基準。 テンプレートの探索順(子テーマ名と親テーマ名をつないだディレクトリ名による多段継承と、system へのフォールバック)、template.yaml のキー、 カテゴリー別・エントリー別テンプレートの置き方、テーマセットによる割り当て、ファイル名の先頭 _ と直接表示の禁止、 アップデートで上書きされる場所、acms.js と管理用 CSS の読み込み、テンプレート内のパスの書き換え、 表示に使われているテンプレートの調べ方(デバッグモード)、大規模サイトの設計と運用(子ブログとカテゴリーの使い分け、 下の階層のブログとの共有、開発環境から本番環境への設定の移行、ページ・モジュール・テンプレートのキャッシュ、ベンチマークモード)を扱う。 「新しいテーマを作って」「子ブログ用のテーマを分けたい」「このページのテンプレートはどれ?」 「system のテンプレートを直したい」「画像や CSS のパスが合わない」「acms.js をログイン時だけ読み込みたい」 「子ブログとカテゴリーのどちらにすべき?」「開発環境の設定を本番に反映したい」「表示が重い」と頼まれたときに使う。 a-blog cms theme, child theme, template.yaml, theme
Original author description
a-blog cms(acms)のテーマを作る・継承する・ブログに割り当てる・構成を直すときの手順と判断基準。 テンプレートの探索順(子テーマ名と親テーマ名をつないだディレクトリ名による多段継承と、system へのフォールバック)、template.yaml のキー、 カテゴリー別・エントリー別テンプレートの置き方、テーマセットによる割り当て、ファイル名の先頭 _ と直接表示の禁止、 アップデートで上書きされる場所、acms.js と管理用 CSS の読み込み、テンプレート内のパスの書き換え、 表示に使われているテンプレートの調べ方(デバッグモード)、大規模サイトの設計と運用(子ブログとカテゴリーの使い分け、 下の階層のブログとの共有、開発環境から本番環境への設定の移行、ページ・モジュール・テンプレートのキャッシュ、ベンチマークモード)を扱う。 「新しいテーマを作って」「子ブログ用のテーマを分けたい」「このページのテンプレートはどれ?」 「system のテンプレートを直したい」「画像や CSS のパスが合わない」「acms.js をログイン時だけ読み込みたい」 「子ブログとカテゴリーのどちらにすべき?」「開発環境の設定を本番に反映したい」「表示が重い」と頼まれたときに使う。 a-blog cms theme, child theme, template.yaml, theme
How it works
- 書き始める前に
- テンプレートの探索順
- 土台のテーマとブログに割り当てるテーマを分ける(推奨)
- テーマの割り当て
- template.yaml
- ファイル名の先頭の と直接表示
- アップデートで上書きされる場所
- acms.js・管理用 CSS・テーマ内のパス
- 使われているテンプレートを調べる
- 大規模サイト・複数環境・性能
SKILL.md preview
---
name: acms-theme-development
description: >-
a-blog cms(acms)のテーマを作る・継承する・ブログに割り当てる・構成を直すときの手順と判断基準。
テンプレートの探索順(子テーマ名と親テーマ名をつないだディレクトリ名による多段継承と、system へのフォールバック)、template.yaml のキー、
カテゴリー別・エントリー別テンプレートの置き方、テーマセットによる割り当て、ファイル名の先頭 _ と直接表示の禁止、
アップデートで上書きされる場所、acms.js と管理用 CSS の読み込み、テンプレート内のパスの書き換え、
表示に使われているテンプレートの調べ方(デバッグモード)、大規模サイトの設計と運用(子ブログとカテゴリーの使い分け、
下の階層のブログとの共有、開発環境から本番環境への設定の移行、ページ・モジュール・テンプレートのキャッシュ、ベンチマークモード)を扱う。
「新しいテーマを作って」「子ブログ用のテーマを分けたい」「このページのテンプレートはどれ?」
「system のテンプレートを直したい」「画像や CSS のパスが合わない」「acms.js をログイン時だけ読み込みたい」
「子ブログとカテゴリーのどちらにすべき?」「開発環境の設定を本番に反映したい」「表示が重い」と頼まれたときに使う。
a-blog cms theme, child theme, template.yaml, theme set, path rewrite, acms.js, large site, multi-blog, staging, deploy, cache.
テンプレートの記法は acms-template-acms(標準)/ acms-template-twig(Twig)、サイトの構成の判定は acms-project-triage が担う。
license: MIT
compatibility: a-blog cms Ver. 3.2 以上
metadata:
acms-min-version: "3.2"
status: stable
---
# a-blog cms のテーマ開発
公式ドキュメント:
- テーマ: <https://developer.a-blogcms.jp/document/themes/>
- テーマの継承: <https://developer.a-blogcms.jp/document/themes/inherit.html>
- テーマの設定(テーマセット・template.yaml): <https://developer.a-blogcms.jp/document/themes/config.html>
- パスの書き換え: <https://developer.a-blogcms.jp/document/template/entry-1443.html>
- テンプレートの探し方: <https://developer.a-blogcms.jp/document/template/entry-2313.html>
## 書き始める前に
1. `acms-project-triage` でバージョン・テーマの継承関係・Twig か標準かを確かめる。
2. どのブログ・カテゴリーにどのテーマが割り当てられているかは DB にあり、ファイルからは分からない。利用者に確認する(下の「テーマの割り当て」)。
3. 直すファイルを推測で決めない。デバッグモードで実際に使われているテンプレートを確かめる(下の「使われているテンプレートを調べる」)。
## テンプレートの探索順
- テンプレート・インクルード・テーマ内の画像や CSS は、割り当てられたテーマ → `@` の右側の親テーマ → … → `system` の順に探され、最初に見つかったファイルが使われる。`president@blog@site` なら `president@blog@site` → `blog@site` → `site` → `system`。
- 子テーマには、親と違うファイルだけを置く。親のファイルを丸ごとコピーすると、親の修正が子に届かなくなる。
- `system` は直接編集しない(アップデートで上書きされる)。変えたいファイルだけを自分のテーマの同じパスにコピーして直す。上の探索順により、そちらが優先される。
URL からどのテンプレートが選ばれるか(カテゴリー別・エントリー別を含む)は references/template-resolution.md を読む。
## 土台のテーマとブログに割り当てるテーマを分ける(推奨)
共通のテンプレートを置く土台のテーマ(例: `base`)は、どのブログにも直接割り当てない。ルートブログにも `root@base` のような子テーマを作って割り当て、ルートブログだけで使うテンプレートは `root@base` に置く。子ブログがまだ無いサイトでも同じ構成にする。
理由: URL のパスがテンプレートのファイル名と一致すると、そのテンプレートがテーマの継承をたどって探されて表示される。ルートブログに `base` を直接割り当て、ルートブログ専用のページ `campaign.html` を `base` に置くと、`news@base` を使う子ブログの `/news/campaign.html` でも同じページが表示されてしまう。`forbid_tpl_inheritance_when_path_unresolved` を on にしても、この経路は止まらない(詳細は references/template-resolution.md)。
## テーマの割り当て
| 割り当て先 | 設定する場所 |
|---|---|
| ブログ | 管理画面のブログ編集で「テーマセット」を選ぶ。テーマセットの中身(テーマディレクトリ、template.yaml を優先するか、各テンプレート)は「テーマ > テーマ設定」で作る |
| 子ブログにまとめて | 親ブログのテーマセットで「子ブログにも継承する」を有効にする。テーマセットが無い子ブログにだけ効く |
| カテゴリー | カテゴリー編集で「テーマセット」を選ぶ(「子カテゴリーにも継承する」あり)。ブログのテーマセットより優先される |
| テーマセットが無いとき | 「コンフィグ > テーマ設定(レガシー設定)」の値が使われる |
テーマ設定はルールごとにも上書きでき、ルールの条件に一致したページではその値が使われる。ファイルを置いただけではテーマは切り替わらない。
## template.yaml
- テーマ直下に置き、ページの種類ごとに使うテンプレートを指定する。テーマセットの「テンプレート選択ファイル(template.yaml)の値を優先する」が有効なときだけ読まれ、有効なら管理画面で入れた値より template.yaml の値が優先される。
- template.yaml も継承される。キーごとに子テーマ → 親テーマ → … の順に探し、最初に値があるものを使う。子テーマの template.yaml には変えたいキーだけを書けばよい。
- 本体が読むキーと既定値は references/template-resolution.md の表を見る。表にないキーを書いても本体は読まない。
## ファイル名の先頭の _ と直接表示
`_top.html`・`_entry.html`・`_member/` のように、パスのどこかの階層が `_` で始まるファイルは URL から直接表示できない(新規インストール時の `forbid_direct_access_tpl: /^_/`)。トップ・詳細・インクルード専用の部品・管理用など、URL で単独で開かれては困るテンプレートは `_` で始まる名前にする(`tpl_top` などの設定から使う分には `_` が付いていても問題ない)。古いサイトでこの設定が無い場合の既定値は off なので、`private/config.system.yaml` を利用者に確かめてもらう。
`<html>` と `<body>` を含まない部品は、ログインしていなければ別の設定(`html_format_validate`)でも 404 になる。ただし `<html>` から書いたテンプレートは、`_` で始まらなければ URL から開ける。確かめるときは必ずログアウトした状態で見る(投稿者以上でログインしていると一部の制限が外れる)。
htmx などの Ajax で読み込む部品(`/tpl/include/...` の URL や `<html>` を含まない部品)は、本体が Ajax と判定したリクエストならこれらの制限(`forbid_tpl_url_context`・`html_format_validate`)を受けない。ログアウト状態で curl などからヘッダーを付けずに取得して 404 になっても、それだけで不具合と判断しない。ブラウザの開発者ツールで実際のリクエストの結果を見るか、Ajax と判定される条件(references/template-resolution.md)を揃えて取得する。
## アップデートで上書きされる場所
本体のアップデートで置き換わるのは次の場所。ここに手を入れない。
- `themes/system/`
- `php/`(`php/ACMS/User/` と `php/AAPP/` は除く)
- `js/`、`lang/`
- `acms.js`、`index.php`
- `private/config.system.default.yaml`(設定の上書きは `private/config.system.yaml` に書く)
公式テーマ(`site` など)・自作テーマ・`extension/` は上書きされない。公式テーマを土台にするときも、公式テーマを直接直すより子テーマを作るほうが、公式テーマの更新を取り込みやすい。
## acms.js・管理用 CSS・テーマ内のパス
- `acms.js` は Js モジュール(標準テンプレート)か `module('V2_Js')`(Twig)で `<head>` 内に出力する。
- ログイン中の投稿者以上には、テンプレートに書かなくても本体が `acms.js` と管理画面用の JavaScript を差し込む。一方、ログインしていない閲覧者には、テンプレートで Js モジュールを出力したときだけ組み込み JS が読み込まれる。
- そのため Js モジュールを `Touch_SessionWithContribution` などで囲んでログイン時だけにすると、閲覧者の画面で組み込み JS に頼る機能(`form.js-validator` のフォーム入力チェック、画像のライトボックス、遅延読み込み、地図など)がすべて動かなくなる。この構成にするなら、それらをテーマ側の JavaScript で用意すると決めてからにする。
- 管理用 CSS(`acms-admin.min.css`)は、公式テーマと同じくログイン中だけ読み込んでよい。
テンプレートに書いた画像・CSS・JavaScript のパスがどう書き換わるか、組み込み JS の詳細は references/assets-and-javascript.md を読む。
## 使われているテンプレートを調べる
1. 管理者ユーザーのユーザー編集で「モード」を「デバッグモード」にしてもらう(Ver. 3.1 以降。その管理者だけに効くので、サイト全体の設定を変えなくてよい)。
2. ログインした状態で対象ページを開くと、管理ボックスに表示中のテンプレートのパスとテーマセット名が出る。
3. ページのソースを見ると、インクルードしたファイルのパスが `<!-- Start of include : source=... -->` の HTML コメントで出る(Twig の `include` は Ver. 3.2.15 以降)。
4. 「デバッグモード & ベンチマークモード」にすると、ページ下部に読み込んだテンプレートの一覧も出る(標準テンプレートのインクルードが対象)。
ログアウトした状態の表示を確かめたいときは `config.server.php` の `DEBUG_MODE` を使う方法もあるが、このファイルは DB の接続情報を含むため、エージェントは開かず、利用者に変更を依頼する。
## 大規模サイト・複数環境・性能
子ブログやカテゴリーが多いサイトの構成、開発環境から本番環境への反映、キャッシュや重いページの調査を扱うときは references/large-site.md を読む。特に次の 3 つは誤りやすい。
- テーマ(ファイル)と、テーマセット・モジュール ID・フォーム ID・ルール(DB)は別々に運ぶ。公開後は本番の DB を開発環境の DB で上書きしない。
- コンフィグのインポートは、そのブログの設定を足し合わせず丸ごと入れ替える。
- テンプレートキャッシュはファイルを書き換えても消えない。本番に反映したらテンプレートキャッシュとページキャッシュをクリアする。
## テーマを新しく作るとき
1. 一から作らず、公式テーマ(<https://developer.a-blogcms.jp/document/themes/official-2025.html>)か既存のテーマを親にした子テーマで始められないか検討する。
2. 土台のテーマと、ブログに割り当てる子テーマを分ける(上の推奨)。
3. 標準テンプレートと Twig のどちらで書くかを決める。既存のテーマを継承するなら親に合わせる(Twig は template.yaml の `tpl_twig: enabled` かテーマ設定で有効にする。記法は acms-template-twig)。
4. ブログ・カテゴリーへの割り当てはテーマセットで行うよう利用者に伝える。
Files in this package (5)
- SKILL.md 13 KB
- evals/scenarios.json 9 KB
- references/assets-and-javascript.md 6 KB
- references/large-site.md 18 KB
- references/template-resolution.md 9 KB
Versions
The database has no other skills named acms-theme-development.
Database snapshot: 13.11.2026 · package version 66f8563b8eca (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100acms-static-to-theme
静的な HTML サイト(手書きの HTML、Vite・webpack・静的サイトジェネレーターなどのビルドの成果物、LP 1 枚から多言語のサイトまで)を a-blog cms(acms)のテーマにする「CMS 化」の作業を、環境の確認 → 標準テンプレートか Twig かの決定 → scripts/inventory.sh による棚卸し → ページと要素の機能への割り当て → テーマの作成 → 動的な部分の置き換え → 管理画面での作業の一覧 → 確認、の固定の順序で導く。 共通部分の切り出し、アセットのパス(相対・ルート相対・CSS の中の… - 89wp-theme-development
WordPress theme code review and block theme development patterns for WordPress 6.6+. Use when reviewing theme code, auditing theme.json schema, checking template hierarchy, validating block templates, analyzing global styles, verifying style variations, reviewing template parts,… - 95engineering-cms-developer
Use when Codex should act as the CMS Developer specialist from Agency Agents. Drupal and WordPress specialist for theme development, custom plugins/modules, content architecture, and code-first CMS implementation - 100hugo-theme
Build, customize, and debug advanced Hugo CMS themes — template architecture, asset pipeline (CSS/JS/image processing), shortcodes and render hooks, page bundles, cover images, Hugo Modules, performance, SEO, and CI/CD. Use when working on a Hugo theme or site template layer. Do… - 90wp-theme-development
WordPress theme review for Codex. Use when reviewing block themes, classic themes, or hybrid themes for theme.json structure, templates, template parts, style variations, global styles, and FSE patterns. - 100wordpress-theme-to-emdash
Port a WordPress theme's design and template behavior to an EmDash-powered Astro site. Use for theme migrations, design matching, PHP-template conversion, and CMS wiring. Do not use for WordPress plugin behavior that does not affect the site theme.