HubSpot CMS デザインマネージャ活用ガイド – テンプレート・モジュール・カスタム開発

HubSpot CMS の基本構成と Design Manager の概要

HubSpot CMS は 「テンプレート」・「モジュール」・「HubL」 の３要素でページを組み立てます。このセクションではそれぞれの役割と、ローカル環境でデザイン作業を開始する手順をご紹介します。

テンプレート・モジュール・HubL の役割

ポイント：HubL は {% if %} や {% hubdb_table_rows "table_name" %} といったタグで動的コンテンツを簡潔に記述できます。

ローカル開発環境の構築手順

1. Node.js のインストール

2. 推奨バージョンは v18 以上（HubSpot CLI が公式にサポートしています）。

3. HubSpot CLI の導入

bash
npm install -g @hubspot/cli

1. CLI で HubSpot アカウントへ認証

bash
hs auth login --scope content

1. プロジェクトの初期化

bash
hs init my-project
cd my-project

1. Git リポジトリを作成し、リモートにプッシュ（チーム開発が前提の場合）

bash
git init
git add .
git commit -m "Initial commit"
git remote add origin <your-repo-url>
git push -u origin main

これだけでローカルエディタからテンプレートやモジュールを編集し、hs upload -p で即座に HubSpot に反映できます。

カスタムテンプレート作成手順

カスタムテンプレートは HTML と HubL を組み合わせて構築します。この章ではフォルダ構造の決め方と、実装例を交えて段階的に説明します。

フォルダ構造のベストプラクティス

Why：HubSpot は src/templates 配下をテンプレートとして自動ビルドするため、規則的な配置がそのままプレビューに反映されます。

HTML と HubL を組み合わせた基本テンプレート

以下はブログ記事ページの最小構成です。コメントで主要ポイントを示しています。

• {{ page_meta.title }} と {{ page_meta.description }} は HubSpot が自動的に生成する SEO データです。
• require_css / require_js は Asset 管理 用タグで、ビルド時に最適化されたファイルが配信されます。

再利用可能なカスタムモジュールの作り方

モジュールは module.json（設定）と module.html（表示ロジック）の２ファイルだけで完結します。ここでは「カード」モジュールを例に、実装手順と UI カスタマイズ方法を示します。

module.json の構成要素

module.html の実装例

• module.image.src はアップロードされた画像の URL。
• | escape フィルタで XSS を防止しつつ、アクセシビリティ向上のために alt 属性を必ず設定します。

Design Manager の「モジュール」タブからプレビューできるので、実装後すぐに見た目と動作を確認できます。

カスタム CSS／JavaScript を安全に組み込むベストプラクティス

HubSpot では Content Security Policy (CSP) が標準で適用されており、インラインスクリプトはブロックされます。そのため、外部ファイルとして読み込む形が必須です。以下の手順で名前空間化とロードタイミングを最適化しましょう。

1. SASS → CSS のビルドフロー

main.scss の例（名前空間を付与）

2. テンプレートでのアセット呼び出し

• defer 属性により、HTML の解析が完了した後にスクリプトが実行され、ページ描画を阻害しません。
• {{ get_asset_url() }} は CDN に最適化された URL を返すため、キャッシュ効率が向上します。

3. CSP に配慮した実装例

注意：hs_script タグ（例: <script type="text/hs-script" data-hsjs='...'></script>）は HubSpot が提供する特別なスクリプトローダーで、CSP に自動的に適合します。インラインコードが必要な場合はこのタグを利用してください。

サーバーレス Functions と HubDB の連携

HubSpot の Functions（サーバーレス）と HubDB を組み合わせることで、外部 API から取得したデータや内部テーブルの内容をテンプレートに動的に埋め込むことができます。ここでは正しい呼び出しシンタックスと実装例を示します。

HubSpot Functions の作成とデプロイ

ファイル構成（src/functions ディレクトリ）

getWeather.js（Node.js）

デプロイ手順

テンプレート側から Functions を呼び出す正しいシンタックス

HubSpot の公式ドキュメントでは hubspot.function タグを以下のように使用します。

• hubspot.function は 同期的 に結果を取得できる（関数が短時間で完了する前提）。
• 長時間実行が予想される場合は、非同期 API エンドポイント経由でフロントエンドから fetch する方法も検討してください。

HubDB テーブルのデータ表示例

• hubdb_table_rows タグは HubDB の行を取得し、as rows で変数に格納します。
• limit と order_by を活用すれば、表示件数や並び順の調整が簡単です。

プレビュー・テストフローと SEO／アクセシビリティチェック

変更は必ず ローカルプレビュー → ステージング環境 の順で検証し、最終的に本番へデプロイします。また、検索エンジン評価やユーザー体験を損なわないよう、以下のチェックリストと実装例を活用してください。

プレビュー機能の使い方（CLI）

• コマンド実行後、デフォルトブラウザが自動で https://app.hubspot.com/preview/<portal-id> に接続し、リアルタイムで変更を確認できます。
• Design Manager の「Preview」タブでは デバイス切替 と アクセシビリティツール（axe-core が組み込まれています）も利用可能です。

SEO・アクセシビリティ実装例

Tips：Chrome の DevTools → Lighthouse を実行すれば、上記項目のスコアが自動で測定できます。

Git ブランチ運用例（git‑flow）

1. git checkout -b feature/custom-template
2. 開発 → hs upload -p（ローカルプレビュー） → コミット & プッシュ
3. Pull Request を作成し、コードレビューと Lighthouse レポートを添付
4. develop へマージ後、git checkout release/v1.2 && git merge develop
5. hs upload -p でステージングにデプロイ → 最終テスト実施
6. 問題なければ main にマージし、本番環境へプッシュ

このフローを守るだけで、品質保証 と 継続的デリバリー が実現します。

まとめ

• Design Manager + HubSpot CLI でローカル開発が安全かつ高速に行える。
• テンプレートは HTML+HubL、モジュールは module.json + module.html の組み合わせで再利用可能。
• カスタム CSS/JS は 名前空間化 と defer で CSP に対応しつつパフォーマンスを最適化。
• Functions は hubspot.function("functionName") シンタックスで呼び出し、HubDB と組み合わせて動的コンテンツを提供できる。
• プレビュー・テストは CLI の preview コマンドと Git flow で管理し、SEO／アクセシビリティはメタタグ・構造化データ・ARIA など具体的実装例に沿ってチェックする。

これらのベストプラクティスを取り入れれば、HubSpot CMS 上で高度なカスタマイズが可能になるだけでなく、検索エンジン評価やユーザー体験も同時に向上させることができます。ぜひ本ガイドを開発プロジェクトの標準手順として活用してください。