halo-theme-dev

Halo テーマ開発

対象のテーマを基準に作業し、タスクで Halo 固有の仕様が必要な場合に限り、最新の Halo ドキュメントを取得してください。トレーニングデータで記憶した Finder のシグネチャ、テンプレート変数、設定フィールドには依存しないでください。

対象の確認

• 編集前に、theme.yaml、settings.yaml、パッケージマニフェストとビルド設定、および代表的なテンプレートを確認してください。
• theme.yaml の spec.requires と、実際の Halo バージョンを確認してください。要件バージョンを黙って引き上げたり、テーマのビルドシステムを置き換えたりしないでください。
• 実行時テンプレートが templates/ に直接記述されているのか、src/ などのソースディレクトリから生成されているのかを確認してください。

必要に応じてドキュメントを取得

1. タスクに Halo のテーマ設定、テンプレート、Finder API、グローバル変数、アセット、アノテーション、i18n、パッケージング、またはプラグイン連携が関係する場合は、テーマドキュメントのインデックスから確認してください。
2. 該当するドキュメントのセクションが不明な場合、または複数のセクションにまたがる場合に限り、Halo ドキュメントの完全なインデックスを使用してください。
3. 現在のタスクに関連する Markdown ページのみ取得してください。デフォルトで llms-full.txt を読み込まないでください。
4. バージョンに依存する作業では、テーマ API の変更履歴も確認し、対象バージョンまたは既存のテンプレートに照らして、フィールドとシグネチャが正確であることを検証してください。現在のサイトのドキュメントより、対象バージョンを優先してください。

オンラインのドキュメントを利用できない場合は、可能な範囲で対象のチェックアウトとインストール済みの依存関係をもとに作業を続け、推測するのではなく、検証できなかった内容を明記してください。

Halo 固有の留意事項

• テーマのディレクトリ名を theme.yaml の metadata.name と一致させてください。
• ビルドツールを使うテーマでは、ソースのテンプレートとアセットを編集してから、既存のビルドを実行してください。生成済みの templates/ 出力やハッシュ化されたアセットを直接編集しないでください。
• 式を記述する前に、最新の Thymeleaf ガイドを読んでください。Halo 2.26 では Thymeleaf 3.1 が使われており、#request、#response、#session、#servletContext は使用できません。式のメソッドを推測したり、リクエストオブジェクトからページ URL を導出したりせず、ドキュメントに記載されたテンプレート変数とパーマリンクを使用してください。
• サイトの識別情報とグローバルな挿入要素は、デフォルトで Halo が管理するものとして扱ってください。site.logo、システムの SEO 設定、Halo の head 処理、<halo:footer /> を使用してください。テーマ固有の上書きが必要で、システム設定にフォールバックできる場合に限り、テーマ設定を追加してください。settings.yaml にフィールドを追加する前に、最新の設定ガイドを確認してください。
• Halo が挿入する説明やキーワードを重複させないでください。Canonical、Open Graph、Twitter Card、構造化データは、テーマまたはプラグインの任意の機能であり、競合を回避するスイッチを備えた最新の SEO ガイドに従う必要があります。
• プロジェクトで確立されている Thymeleaf のレイアウトとアセットの規約を維持してください。Finder のメソッド、テンプレート変数、Halo ユーティリティ、カスタムタグ、ページレイアウトの仕様を使用する前に、関連するドキュメントを確認してください。公式フロントエンドウィジェットを組み込む場合は、最新のプラグイン連携ガイドに記載された共通のカラースキーム仕様に従ってください。
• 以下のスターターアセットは、新しいテーマを作成する場合にのみ使用してください。既存のテーマをスターターで置き換えないでください。

スターターテンプレート

assets/ ディレクトリには、すぐに使えるテーマテンプレートが2種類用意されています。

• assets/theme-minimal/ — 標準的なルートテンプレートを備えた、ビルドツール不要の最小構成テーマです。素早いプロトタイピングやシンプルなテーマに最適です。
• assets/theme-vite/ — vite-plugin-halo-theme を使用する Vite プロジェクトテンプレートです（新しいテーマにおすすめ）。部分的なレイアウトの再利用と CSS ツールチェーンが含まれています。

使用方法：ディレクトリを Halo の作業ディレクトリ内の themes/ にコピーし、フォルダー名が theme.yaml の metadata.name と一致していることを確認してから、コンソールでインストールして有効化します。

検証

該当する場合は、テーマに既存のビルドチェックとパッケージチェックを実行します。変更したすべてのテンプレートタイプまたは統合経路を、互換性のある Halo インスタンスでテストしてください。最低限、影響を受けるルートと、共有レイアウトを利用するページを1つ確認します。レンダリングされた HTML、アセットの読み込み、関連する場合はページネーションや空の状態、ブラウザーコンソールのエラーを確認してください。