HubL syntax overview

HubSpot’s CMS uses the HubSpot Markup Language, referred to as HubL (pronounced “Hubble”). HubL is HubSpot’s extension of Jinjava, a templating engine based on Jinja. HubL uses a fair amount of markup that is unique to HubSpot and does not support all features of Jinja.

This article will take you through the basics of HubL's features and syntax.

Similar to other commonly used templating languages such as PHP, HubL can be mixed into your HTML in coded templates files or HubL template modules. In order to differentiate, where your HubL starts and ends, you will need to learn a few key symbols that act as delimiters.

HubL statements are used to create editable modules, define conditional template logic, set up for loops, define variables, and more. Statements are delimited by {%.  They do not print anything to the page.

Expressions print values stored in the context of the template. Expressions are delimited by {{. For example, a variable must be defined as a statement, but then a HubL expression would be used to print the variable.

The 'do' tag works exactly like the regular statements {% ... %};  This can be used to modify lists and dictionaries.

Note: When adding to arrays, you want to use .append() and when adding to objects, you want to use .update()

The final type of delimiter that you may encounter or decide to employ while developing with HubL, is a HubL comment. Comments are defined by a {#. 

Modules are dynamic areas of a template that can be customized by the end user in the content editor. For example, if you were coding a template file from scratch, you would add modules to templates with HubL tags, to give your content creators the ability to edit areas of the page.

Module tags are made up of the following components:

• Type of module: specifies which module to render. Please refer to the HubL Supported Tags page for a listing of the different types of modules available.
• A unique name for that module: gives the module a unique identity in the context of the template.
  
• Path: depending on the tag, defines the location of where the module is in the design manager. The path for HubSpot default modules should always start with @hubspot/ followed by the type of module. See the example below and the using modules in templates page for more. 
• Parameters: optionally specify additional module information.

The example above is a text module with the label and value parameters defined. The label defines the help text in the editor and value sets the default text for that module. See the sample gif below for how this looks inside of the editor.

You can learn more about using modules in templates, here. 

HubL includes many predefined HubSpot variables that print their helpful values from the app. In addition, you can define your own variables in a template. In the following example, a variable named primaryColor is defined in a statement and then printed with a HubL expression. This example mixes the HubL variable with CSS. 

HubL macros allow you to print multiple statements with a dynamic value. This technique proves useful when you find yourself writing the same basic code blocks over and over, but only need to change certain values. In the following example, a macro is used to print a CSS3 transition property that includes all the vendor prefixes. You can learn more about macros, here. 

Filters can be added to your HubL to transform or alter the value of a template variable. A simple example displayed below is formatting a date variable. Filters use a | (pipeline symbol) and are applied without spaces to a variable.

In the example below, assume a blog post was published on the 29th of April. The publish date of the post is formatted with a datetimeformat filter. You can view a full list of filters here.

While filters affect how variables render, functions process value and account information and render that info. For example, a function can be used to get the total number of posts for a particular blog or to lighten/darken a color variable by a particular amount.

The example would print the total number of blog posts from the designers.hubspot.com/blog. It uses a Blog ID (available in the URL of the blog dashboard) parameter to specify which blog to target. You can view a full list of functions here.

If statements allow you to use conditional logic to dictate how your template will render conditional logic in HubL statements for if, elif, else, and endif. An if statement must begin with an if and end with an endif. 

The example below defines a choice module that lets the end user select a department from a dropdown. Depending on what the user selects in the editor, the template will generate a dynamic heading for a careers page. This example requires the use of the export_to_template_context parameter.

For loops allow you to iterate over items stored in a sequence. They will most commonly be used with rendering blog content in a listing format. For loops begin with a for statement and end with an endfor statement.

In the example below, an array of types of bears is stored as a variable called bears. A for loop is then used to iterate through the different types of bears printing a list item for each type. 

Below are a few other miscellaneous templating features that may be useful, as you develop with HubL.

Many other languages share the same delimiters as HubL, which can create issues when working in coded files on the CMS. If you want to use a HubL delimiter for a different language, you need to wrap that code in:

You can include multiple .html files in one HubL template using the include tag. In order to create an HTML file that does not require the standard template variables, you must uncheck the option "Make template available for new content." The syntax is displayed below:

You can also compile multiple CSS files into a single CSS file with the same include tag. When you publish the parent file, the child file will be compiled into a single minified CSS file with the parent's code. 

When creating complex templates, you can use create compartmentalized blocks that extend a parent template.

First, you'll create a main template that includes the required standard_header_includes and standard_footer_includes variables. Within that template, you need to define a unique block using the following syntax where my_sidebar is a unique name:

Next, you can create a child HTML file that will populate that block. First, you must declare an extends statement that references the path to the parent. This block of code would be rendered in the parent template but maintained in another smaller and more manageable file. This technique is not for everyone but can be useful to stay organized when coding complex email or page templates.  When using this technique, you should choose the child template, when creating content.

In the page editor, you can copy the HubL markup for a drag and drop section to reuse the code as needed. This can be helpful when wanting to recreate a drag and drop section in a coded file.

Learn more about copying section HubL.