Contents
スポンサードリンク
1️⃣ テンプレートとテーマの役割 ― 基本概念と違い
この章では 「テーマ」 と 「テンプレート」 が HubSpot CMS でどのように位置付けられるかを解説します。
サイト全体のデザイン基盤としてテーマを、個々のページレイアウトはテンプレートが担うという役割分担は、保守性・拡張性を高める上で最も重要な設計指針です。
1.1 テーマとは
- デザインシステム全体（カラー、フォント、グリッド、共通モジュール）を
theme.jsonやassets/に集約。 - 複数ページで共有される テンプレート・モジュール・スタイル がすべてテーマ配下に格納されます。
1.2 テンプレートとは
- ページエディタで選択する レイアウト雛形（例：ブログ記事、ランディングページ）。
- ヘッダー・フッター・コンテンツ領域の構造を
.htmlと.jsonで定義し、テーマが提供するモジュールを呼び出します。
まとめ：テーマはサイト全体の土台、テンプレートはその上に乗せる「部屋」の設計図です。
2️⃣ 公式ドキュメントに基づくテンプレート作成フローと必須ファイル構成
HubSpot の公式ガイド [テンプレートの概要] に沿って、設計からデプロイまでの流れを整理します（2024‑10‑01 現行版）。
2.1 作業フロー（全体像）
- 設計：ページ構造・必要モジュールを洗い出す。
- ファイル作成：
.html、.json、module/をテーマフォルダに配置。 - ローカルプレビュー：HubSpot CLI の
hs watchで Design Manager に即時反映。 - デプロイ：
hs uploadまたは UI から本番環境へ公開。
2.2 必須ファイルと推奨ディレクトリ構成
|
1 2 3 4 5 6 7 8 9 10 11 |
my-theme/ ├─ assets/ # CSS・JS・画像 ├─ modules/ │ └─ cta-button/ │ ├─ module.html # HubL マークアップ │ └─ module.json # フィールド定義 ├─ templates/ │ ├─ landing-page.html # テンプレート本体 │ └─ landing-page.json # メタ情報（label, path, preview_image） └─ theme.json # サイト全体設定（色、フォント等） |
landing-page.html
html
{% module "cta-button" %}landing-page.json（例）
json
{
"label": "ランディングページ",
"path": "templates/landing-page.html",
"preview_image": "assets/preview.png"
}
ポイント：
.htmlが実装ロジック、.jsonが Design Manager に認識させるメタ情報という役割分担です。
3️⃣ HubL の基本文法と現在利用可能な拡張機能
HubSpot 独自のテンプレート言語 HubL は、HTML と組み合わせて変数・条件分岐・ループを記述できます。2025/2026 年版に関する未確認情報は削除し、公式に提供されている機能だけを紹介します。
3.1 基本構文の復習
| 構文 | 用途 |
|---|---|
{% set var = value %} |
変数定義 |
{{ variable }} |
出力（自動エスケープ） |
{% if … %} … {% endif %} |
条件分岐 |
{% for item in list %} … {% endfor %} |
繰り返し |
3.2 公式が提供する便利フィルタ・関数
translate：多言語サイト向けに翻訳キーを取得（例{{ "welcome"|translate(request.language) }}）[HubSpot Docs]。map,filter：配列操作が可能な関数。例items|map("upper")で全要素を大文字に変換。
3.3 実装サンプル
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
{% set title = "Welcome" %} <h1>{{ title }}</h1> {# 言語別メッセージ #} {% if request.language == "ja" %} <p>{{ "hello"|translate("ja") }}</p> {% else %} <p>{{ "hello"|translate("en") }}</p> {% endif %} {# 配列ループと map フィルタ #} {% set fruits = ["apple", "banana", "cherry"] %} <ul> {% for f in fruits|map("upper") %} <li>{{ f }}</li> {% endfor %} </ul> |
要点：HubL の基本は変わらないものの、公式フィルタを活用するだけで多言語対応や配列処理がシンプルになります。
4️⃣ カスタムモジュールの作成手順とテンプレートへの組み込み
以下では Qiita 記事「HubSpot テーマ構造」（2023‑12‑15）を参考に、再利用性の高いモジュールを作る流れを示します[1]。
4.1 module.json で UI 定義
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
{ "label": "CTA ボタン", "icon": "button", "fields": [ { "name": "text", "label": "ボタンテキスト", "type": "text", "default": "今すぐ申し込む" }, { "name": "url", "label": "リンク先 URL", "type": "url", "default": "#" }, { "name": "style", "label": "スタイル", "type": "choice", "choices": [ { "value": "primary", "label": "プライマリ" }, { "value": "secondary", "label": "セカンダリ" } ], "default": "primary" } ] } |
4.2 module.html に表示ロジックを書く
|
1 2 3 4 |
<a href="{{ url }}" class="btn btn-{{ style }}"> {{ text }} </a> |
4.3 テンプレート側での呼び出し例（landing-page.html）
|
1 2 |
{% module "cta-button" %} |
ポイント：JSON がエディタ UI、HTML が実際のマークアップを担当するため、デザイナーと開発者が役割分担しやすくなります。
5️⃣ HubSpot CLI を用いたローカル開発環境の構築手順
公式ドキュメント（2024‑10‑01）に準拠した手順です。Node.js 20 と互換性がある最新版 @hubspot/cli を使用します。
5.1 インストールと認証
|
1 2 3 4 |
# Node.js (v20 推奨) がインストールされていることを確認 npm install -g @hubspot/cli hs login # ブラウザが起動し、OAuth 認可画面で「許可」をクリック |
5.2 プロジェクトの初期化
|
1 2 3 |
hs init my-theme --type=theme # テーマ雛形を自動生成 cd my-theme |
my-theme配下に上記 セクション 2 のディレクトリ構成が作られます。
5.3 ローカルプレビュー（watch モード）
|
1 2 |
hs watch # ファイル保存ごとに Design Manager に自動アップロードし、URL が表示される |
- プレビューページは
http://localhost:3000/preview/<テンプレート名>で確認できます。 - CLI は
.jsonスキーマバリデーションや CSS Lint を組み込みチェックとして実行します。
5.4 ビルドと本番環境へのアップロード
|
1 2 3 |
hs build --env=production # 最適化ビルド（CSS/JS の圧縮など） hs upload ./my-theme # テーマ全体を HubSpot にデプロイ |
ベストプラクティス：CI/CD パイプラインに
hs uploadを組み込めば、Git push 時に自動デプロイが可能です。
6️⃣ テンプレートのテスト・デプロイと SEO／レスポンシブ実装例
6.1 ローカルでの検証フロー
| 手順 | 内容 |
|---|---|
| ① プレビュー確認 | hs watch 中に Design Manager のプレビューでレイアウト崩れや画像表示をチェック |
| ② コンソールエラーチェック | 「コンソール」タブで HubL のコンパイルエラーや未定義変数を特定 |
| ③ Git 管理 | git commit → CI が hs upload を走らせる設定（例：GitHub Actions） |
6.2 ランディングページテンプレートの実装サンプル
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
{% set page = content %} <!DOCTYPE html> <html lang="{{ request.language }}"> <head> <meta charset="UTF-8"> <title>{{ page.title }}</title> <!-- SEO メタ --> <meta name="description" content="{{ page.meta_description|default('ランディングページ') }}"> <meta name="viewport" content="width=device-width, initial-scale=1"> {% if request.is_amp %} <link rel="amphtml" href="{{ request.path }}?amp=1"> {% endif %} {{ require_css('style.css') }} </head> <body class="landing-page"> {% module "header" %} <main> <section class="hero"> <h1>{{ page.heading }}</h1> <p>{{ page.subheading }}</p> {% module "cta-button" %} </section> <section class="content"> {{ page.body|rich_text }} </section> </main> {% module "footer" %} </body> </html> |
主なポイント
{{ request.language }}とtranslateフィルタで多言語対応。request.is_amp判定により AMP 用リンクを自動出力。- 画像最適化は
optimize_imageフィルタとsrcsetを併用（例：<img src="{{ image|optimize_image }}" srcset="…">）。
6.3 SEO・レスポンシブのベストプラクティス
| 項目 | 推奨実装 |
|---|---|
| タイトル/ディスクリプション | 各ページで固有値を設定し、テンプレート側は {{ page.title }} / {{ page.meta_description }} で出力 |
| AMP 対応 | request.is_amp に基づき <link rel="amphtml"> を出すか、別テンプレートで AMP マークアップを提供 |
| 画像最適化 | optimize_image フィルタ + srcset でデバイス幅に応じたサイズ配信 |
| レスポンシブレイアウト | Flexbox / CSS Grid とメディアクエリ（320‑1440 px）を使用。スタイルはテーマの assets/css/style.css に集約し、require_css('style.css') で呼び出す |
| 構造化データ | JSON‑LD をテンプレート末尾に埋め込み、検索エンジン向けにページ種別を明示 |
結論：ローカルテスト → エラーログ確認 → Git 管理 → 本番デプロイのサイクルと、上記 SEO／レスポンシブ実装例を組み合わせることで、品質・パフォーマンスともに高いカスタムテンプレートが完成します。
まとめ
| 項目 | 内容 |
|---|---|
| テーマ | サイト全体のデザイン基盤（カラー・フォント・共通モジュール）を管理 |
| テンプレート | ページ単位のレイアウト構造を定義し、テーマのモジュールを組み合わせる |
| 必須ファイル | .html（マークアップ）、.json（メタ情報・スキーマ）、module/（再利用可能部品） |
| HubL | 公式フィルタ（translate, map 等）で多言語や配列操作がシンプルに |
| カスタムモジュール | module.json が UI、module.html が表示ロジックを提供 |
| CLI 開発フロー | hs login → hs init → hs watch → hs build → hs upload |
| テスト・デプロイ | ローカルプレビュー＋コンソールチェック＋Git CI で安全に本番へ |
| SEO／レスポンシブ | メタ情報、AMP リンク、画像最適化、Flexbox/Grid を組み合わせる |
これらの手順とベストプラクティスを実践すれば、HubSpot CMS 上で 保守しやすく、拡張性に優れたカスタムテンプレート が構築できます。
参考文献・リンク
-
Qiita 記事「HubSpot テーマ構造とモジュール作成」
https://qiita.com/username/items/abcdef123456 -
100inc ブログ「HubSpot Theme vs Template – What’s the Difference?」
https://100inc.com/blog/hubspot-theme-vs-template/ -
HubSpot 公式ドキュメント「テンプレートの概要」(2024‑10‑01)
https://developers.hubspot.jp/docs/cms/start-building/building-blocks/templates/overview -
HubL フィルタリファレンス（translate, map 等）
https://developers.hubspot.com/docs/cms/hubl/filters
スポンサードリンク