HubL (HubSpot Markup Language) basics

What is HubL?

HubLis a template engine designed by HubSpot. Based on Python's Jinja2, HubSpot-specific variables, filters, and tags have been added. HubL is embedded in an HTML file, processed on the server side, and finally output as HTML.

Basic syntax: 3 delimiters

HubL has three types of notation for different purposes. This is the basic unit of HubL.

{# ====== ① Output tag {{ }} ====== #}
{# Output variable value to HTML #}
<h1>{{ content.name }}</h1>
<p>{{ content.meta_description }}</p>{# Process and output using filters #}
<p>{{ content.publish_date|datetimeformat("%Y year %m month %d day") }}</p>{# ====== ② Statement tag {% %} ====== #}
{# Set value to variable (no output) #}
{% set site_name = "Sample Co., Ltd." %}

{# Conditional branch (no output) #}
{% if content.featured_image %}
  <img src="{{ content.featured_image }}" alt="{{ content.featured_image_alt_text }}">{% endif %}

{# ====== ③ Comment {# #} ====== #}
{# This comment is also not displayed in the HTML source #}
{# TODO: Add mobile support #}

Variables/sets/data types

Defining variables (set)

{% set %} Define variables with tags. Once defined, variables can be reused within the template.

{# string #}
{% set company_name = "Sample Co., Ltd." %}

{# number #}
{% set max_posts = 6 %}

{# Boolean value #}
{% set is_published = true %}

{# list (array) #}
{% set nav_items = ["Home", "service", "Company Profile", "inquiry"] %}

{# dict — key-value pairs #}
{% set form_ids = {
  "contact"  : "xxxx-xxxx-contact",
  "seminar"  : "xxxx-xxxx-seminar",
  "download" : "xxxx-xxxx-download"
} %}

{# Get value from dictionary #}
{{ form_ids["seminar"] }}
{{ form_ids.contact }}     {# Also accessible with dot notation #}

Update variables (namespace pattern)

HubL does not allow you to directly rewrite variables in the outer scope within a loop. namespace You can update variables outside the loop from within the loop. This is a pattern often used in practice.

{# Ordinary set cannot update outer variables within a loop (NG) #}
{% set content_type = "blog" %}
{% for tag in content.tag_list %}
  {% set content_type = tag.slug %}  {# ← This is only valid inside a loop! #}
{% endfor %}

{# ✅ Correct pattern using namespace #}
{% set ns = namespace(content_type="blog") %}
{% for tag in content.tag_list %}
  {% if tag.slug starts_with "type:" %}
    {% set ns.content_type = tag.slug|replace("type:", "") %}
  {% endif %}
{% endfor %}

{# Get the correct value after the loop #}
<div class="post-type-{{ ns.content_type }}">...</div>

Control syntax: if / for / unless

① Conditional branching (if / elif / else / endif)

{# Basic if #}
{% if content.featured_image %}
  <img src="{{ content.featured_image }}" alt="{{ content.featured_image_alt_text }}">{% endif %}

{# if / elif / else #}
{% if content_type == "seminar" %}
  <span class="badge badge-seminar">セミナー</span>{% elif content_type == "news" %}
  <span class="badge badge-news">お知らせ</span>{% elif content_type == "case" %}
  <span class="badge badge-case">事例</span>{% else %}
  <span class="badge badge-blog">ブログ</span>{% endif %}

Compound condition using {# not / and / or #}
{% if content.featured_image and content.featured_image_alt_text %}
  {# Display only when there is both image and alt #}
{% endif %}

{% if not content.archived %}
  {# Display only unarchived articles #}
{% endif %}

Frequently used comparison operators/test operators

② Loop (for/endfor)

{# List loop #}
{% set nav_items = [
  {"label": "Home",     "url": "/"},
  {"label": "service", "url": "/service"},
  {"label": "Company Profile", "url": "/about"}
] %}

<ul>{% for item in nav_items %}
  <li><a href="{{ item.url }}">{{ item.label }}</a></li>{% endfor %}
</ul>{# loop variable (special variable that can be used inside the loop) #}
{% for post in posts %}
  {% if loop.first %}<div class="first-item">{% endif %}

  <article class="post-item post-{{ loop.index }}">
    <h2>{{ post.name }}</h2>
  </article>

  {% if loop.last %}</div>{% endif %}
{% endfor %}

{# Numeric loop with range() #}
{% for i in range(1, 6) %}
  <span>{{ i }}</span>   {# 1, 2, 3, 4, 5 #}
{% endfor %}

{# else clause: if list is empty #}
{% for post in posts %}
  <article>...</article>{% else %}
  <p>記事がありません</p>{% endfor %}

loop variable list

③ unless (negative version of if)

{# unless is "unless". Synonymous with if using not #}
{% unless content.archived %}
  <div class="post-content">...</div>{% endunless %}

{# The above is the same as below #}
{% if not content.archived %}
  <div class="post-content">...</div>{% endif %}

Defining and reusing macros

macrois a mechanism for defining HTML patterns that are used repeatedly as functions. Since you can pass arguments, you can efficiently manage parts that "look the same but have different contents."

{# ====== Macro definition ====== #}

{# Card component macro #}
{% macro render_card(title, description, url, badge="", image="") %}
  <div class="card">
    {% if image %}
      <img src="{{ image }}" alt="{{ title }}">
    {% endif %}
    {% if badge %}
      <span class="badge">{{ badge }}</span>
    {% endif %}
    <h3><a href="{{ url }}">{{ title }}</a></h3>
    <p>{{ description|truncate(80) }}</p>
  </div>{% endmacro %}

{# ====== Macro call ====== #}

{# Basic call #}
{{ render_card(
  title="How to achieve results with HubSpot",
  description="We will explain specific methods of marketing measures using HubSpot.",
  url="/blog/hubspot-tips"
) }}

{# Call with badge/image #}
{{ render_card(
  title="[Seminar] How to use HubSpot",
  description="This is an online seminar introducing the latest HubSpot usage examples in 2024.",
  url="/blog/seminar-2024",
  badge="Seminar",
  image="https://example.com/seminar.jpg"
) }}

{# Combine with loop in blog list #}
{% set posts = blog_recent_posts("default", 6) %}
{% for post in posts %}
  {{ render_card(
    title=post.name,
    description=post.meta_description,
    url=post.absolute_url,
    image=post.featured_image
  ) }}
{% endfor %}

Split macro into files and import

As the number of macros increases, organize them into a dedicated parts file. import or from … import You can read it with .

{% macro render_card(title, description, url, badge="") %}
  ...{% endmacro %}

{% macro render_badge(label, type="default") %}
  <span class="badge badge--{{ type }}">{{ label }}</span>{% endmacro %}

{# Import and use the entire file #}
{% from "../partials/macros.html" import render_card, render_badge %}

{% set posts = blog_recent_posts("default", 9) %}
{% for post in posts %}
  {{ render_card(post.name, post.meta_description, post.absolute_url) }}
{% endfor %}

Built-in variables list

HubSpot CMS templates provide many built-in variables that can be used in specific contexts. Pay attention to the scope (where you can use it).

content — content information (most important)

This is an object that contains information about the currently displayed page, article, email, etc. These are the most frequently used variables that can be used throughout the template.

request — Request information

Other frequently used variables

Complete guide to filters

A filter is a mechanism for processing and converting variable values. {{ 変数|フィルター名 }} used in the form of|You can chain multiple filters by connecting them with (pipes).

{# Single filter #}
{{ content.name|upper }}

{# Filter with arguments #}
{{ content.meta_description|truncate(100) }}

{# Chain (connect multiple filters) #}
{{ content.name|truncate(30)|upper }}

string manipulation filter

date and time filter

Numeric/list filter

Blog-specific HubL function list

We will organize the HubL functions required to implement the blog function. These are the most frequently used functions in blog-related templates.

Article retrieval function

{# Get 6 latest articles #}
{% set recent_posts = blog_recent_posts("default", 6) %}

{# Get articles by specifying tags (seminar articles only) #}
{% set seminar_posts = blog_posts("default", 3, 0, "seminar") %}

{# Pagination using offset (2nd page: 11-20 items) #}
{% set page2_posts = blog_posts("default", 10, 10) %}

{# 5 popular articles #}
{% set popular = blog_popular_posts("default", 5) %}

{# Total number of articles #}
{% set total = blog_total_post_count("default") %}
<p>全{{ total }}件の記事</p>

URL/link generation function

{# Generate tag archive URL #}
<a href="{{ blog_tag_url("default", "seminar") }}">セミナー一覧へ</a>{# Example output: /blog/tag/seminar #}

{# Dynamically generate tag list link in navigation #}
{% set tag_nav = [
  {"label": "Blog",         "slug": "blog"},
  {"label": "Seminar",       "slug": "seminar"},
  {"label": "notice",       "slug": "news"},
  {"label": "Introduction example",       "slug": "case"}
] %}

<nav class="blog-nav">
  <a href="/blog">すべて</a>
  {% for tag in tag_nav %}
    <a href="{{ blog_tag_url("default", tag.slug) }}"
       {% if content.tag.slug == tag.slug %}
         class="is-active" aria-current="page"
       {% endif %}>
      {{ tag.label }}
    </a>
  {% endfor %}
</nav>{# Generate pagination URL #}
<a href="{{ blog_page_link(current_page_num + 1) }}">次へ</a>

Main properties of article objects

blog_recent_posts() This is a list of properties that can be used with article objects obtained with etc.

How to use HubL and JavaScript

HubL and JavaScript are both used in HubSpot templates, but they have distinctly different roles. A proper understanding of the differences between the two will help you choose the appropriate implementation.

{# Pass server-side data as JS variables in HubL #}
{# → Pattern to use when you want to use HubSpot data from JS #}

<script>
  // Pass HubL variables to JS
  const hubspotConfig = {
    portalId  : {{ hub_id }},
    pageId    : {{ content.id }},
    pageTitle : "{{ content.name|escape }}",
    contentType: "{{ ns.content_type }}",
    formIds   : {
      seminar  : "{{ form_ids.seminar }}",
      download : "{{ form_ids.download }}"
    }
  };

  // After this it can be processed as JS
  console.log(hubspotConfig.pageTitle);

  // Dynamically switch forms depending on content type
  hbspt.forms.create({
    portalId : hubspotConfig.portalId,
    formId   : hubspotConfig.formIds[hubspotConfig.contentType]
               || hubspotConfig.formIds.download,
    target   : '#hs-form-area'
  });
</script>

Chapter 2 Summary