HubL cheat sheet

Delimiters

{# A module's heading field #}
<h1>{{ module.heading }}</h1>

Variables

Set your own with set. Strings, numbers, booleans, lists and dicts work as in Jinja:

{% set title = "Pricing" %}
{% set sizes = [480, 960, 1440] %}
{% set button = {"label": "Start free", "url": "/start/"} %}

{{ title ~ " | transjt" }}    {# ~ joins strings #}
{{ sizes[0] }}                {# 480 #}
{{ button.label }}            {# or button["label"] #}
{% do sizes.append(1920) %}   {# change a list in place #}

HubSpot provides these on every page:

If and for

{% if module.items %}
  <ul>
  {% for item in module.items %}
    <li class="{{ 'is-first' if loop.first else '' }}">{{ loop.index }}. {{ item.title }}</li>
  {% endfor %}
  </ul>
{% elif is_in_editor %}
  <p>Add an item in the sidebar.</p>
{% else %}
  {# Nothing to show on the live page #}
{% endif %}

• In a loop: loop.index (from 1), loop.index0 (from 0), loop.first, loop.last, loop.length.
• {% unless condition %} … {% endunless %} is the opposite of if.
• Tests read like English: {% if module.subtitle is defined %}, is string, is number, is even, is divisibleby 3.
• Operators: ==, !=, and, or, not, in.

Filters

A filter changes a value after a pipe, {{ value|filter }}, and filters chain from left to right.

Functions

{% for post in blog_recent_posts("default", 3) %}
  <a href="{{ post.absolute_url }}">{{ post.name }}</a>
{% endfor %}

Tags

Every page template needs {{ standard_header_includes }} before the closing </head> and {{ standard_footer_includes }} before the closing </body>: they bring in HubSpot's own scripts, styles and tracking.

<!--
  templateType: page
  isAvailableForNewContent: true
  label: Landing page
-->
{% extends "./layouts/base.html" %}
{% block body %}
  {% dnd_area "main" label="Main" %}
    {% dnd_section %}
      {% dnd_column %}
        {% dnd_row %}
          {% dnd_module path="@hubspot/rich_text" %}{% end_dnd_module %}
        {% end_dnd_row %}
      {% end_dnd_column %}
    {% end_dnd_section %}
  {% end_dnd_area %}
{% endblock %}

Modules and fields

A module is a folder ending in .module with module.html (HubL), module.css, module.js, fields.json and meta.json. In module.html, each field is module. plus its name:

{% set img = module.image %}
<section class="hero hero--{{ name }}">
  {% inline_text field="heading" value="{{ module.heading }}" %}
  {% if img.src %}
    <img src="{{ img.src }}" alt="{{ img.alt|escape_attr }}" width="{{ img.width }}" height="{{ img.height }}" loading="lazy">
  {% endif %}
</section>

• {{ name }} is the module instance's unique name: use it to scope CSS to one instance.
• inline_text and inline_rich_text make a field editable right on the page in the editor.
• module.css supports almost no HubL (only helpers such as module_asset_url) and can't read field values; module.js supports none. For a value from a field, put a {% require_css %} block in module.html.
• A colour picked in a field and printed in an inline style="" wins over the module's CSS: check module.html first when a style won't change.

Debugging

• {{ module|pprint }} prints a value with its type, right on the page. Remove it before you publish.
• Add ?hsDebug=true to a live page's URL: its CSS and JavaScript load unminified and uncombined, nothing comes from the cache, and the end of the page's source lists HubL errors and warnings, the render time and whether the page can be prerendered.
• The Design Manager marks HubL errors in the file while you edit. With the HubSpot CLI, hs cms lint <path> checks files, and uploads report fatal errors in the terminal.
• HubSpot re-renders the pages that use an updated module or template by itself, which can take a few minutes. If a live page still shows the old version, publish it again.

HubL in transjt themes

When you export a design or an AI build, transjt writes the theme for you: templates with drag-and-drop areas, and one module per section with its texts, images, links and colours as fields. Your marketing team edits those fields in the page editor; nobody has to write HubL.

To adjust a theme yourself, keep your own CSS and JavaScript in custom.css and custom.js: they stay in place when you export again. See For HubSpot developers and Using your theme in HubSpot.

The full HubL reference is in HubSpot's developer documentation.