HTML + HubL Templates

Last updated:

HTML + HubL templates can be used for every type of template on the HubSpot CMS. These templates are .html files that support the HubL templating language. Because these coded templates support HubL the best previewing experience is using the template preview in the Design Manager or viewing pages on a sandbox account. HTML + HubL templates can contain Partials, which can be used to separate commonly used chunks of code, such as a header or footer.

HTML + HubL templates give greater control to developers than visual design manager drag and drop templates. Developers in-turn can provide better experiences for content creators through drag and drop functionality - which is only possible with HTML + HubL templates.
image1-2

The example from the screenshot comes from the base.html file in our cms-theme-boilerplate. The boilerplate is designed to be a headstart for developers building a great website on the HubSpot CMS software. The boilerplate represents HubSpot’s opinionated best practices, and we intend to learn from your feedback and similar projects. We hope it offers inspiration and helps accelerate your website projects.

Familiarity and Tooling

Since HTML + HubL templates are coded files, existing tools that developers already have can be used to edit them locally. The best local development experience is using our local development tools. With them, you can upload, fetch, watch, create and otherwise securely manage files in the developer file system as well as the file manager.

For developers familiar with other templating languages, since these templates revolve around HTML and a sprinkling of HubL where needed, it is easy to see the similarities with other templating languages you may have used before. This makes it easy to transition over from other platforms. The core difference is that HubSpot takes an opinionated stance on the best ways to do some things to offer the best experience for content creators, and also take much of the maintenance and performance optimization work off of the developer. 

For example: If you want to load CSS files, instead of using <link rel="stylesheet" type="text/css" href="theme.css"> for stylesheets we encourage using requires at the template level, keeping module-specific CSS in the module as well as the meta.json files in modules to specify stylesheets that may be shared across modules.

The advantage of this approach is that you transfer the work of conditionally loading that CSS from you and your development tools to HubSpot. The HubSpot CMS knows if a content creator adds an instance of a module to a page and as such can conditionally load the CSS required. Minimizing the CSS loaded to just what is necessary, ensuring a faster loading experience. The HubSpot CMS also takes this CSS and does performance enhancement handling minification and combining of the files as necessary, as well as serving them via CDN automatically without any effort on your part.

To make development on HubSpot easier there are  tools both community and HubSpot created which are worth looking into. Since HubL is based on Jinja and follows mostly the same syntax you can usually use a language plugin in your local editor for jinjava for better syntax highlighting of HTML + HubL files.

Template Annotations

Template annotations provide a local development-friendly way of indicating to HubSpot important template settings.  Because the annotation is part of the code, you can change the annotation at a later time to change the templateType.

HTML
<!--
  templateType: page
  isAvailableForNewContent: false
  enableDomainStylesheets: false
  label: Homepage
-->

<!doctype html>

<html>
...

These template settings determine how and if templates appear to content creators and whether they use domain-wide stylesheets.

Template Annotations
Annotation Description Possible Values
templateType
Specifies which template type a file is.
isAvailableForNewContent
Specifies if a template is available for selection in the content creation process.

true, false

enableDomainStylesheets
Specifies if the template should load stylesheets defined under settings > website > pages

true, false

Label
User friendly description of the template, displayed in the template selection screen

About Page, Homepage, Pricing, Any custom string

HubSpot's templates require two tags to be present unless the file is a template partial. The two tags are:

  • {{ standard_header_includes }} - Used to intelligently add combined and minified required CSS. 
  • {{ standard_footer_includes }} - Used to intelligently add javascript to the bottom of a page dynamically, for things like the HubSpot tracking script, and modules.

These tags must be present in a template or it's partial children to be published and used.

Partials

Template partials are HTML + HubL files that can be included in other coded files. This allows developers to take a more modular approach to build complex documents and share markup between multiple templates. Common examples of this would be headers, footers, sidebars, etc, and are often the same, so using partials to manage that content is an easy experience. To create an HTML file that does not require the standard required template variables, you must include the annotation isAvailableForNewContent: false at the top of the file.

Standard Partials

A type of template partial that can be used across multiple templates with content that may be edited on individual pages. templateType: page, and the isAvailableForNewContent: false

HubL
{% include "../partial/sidebar.html" %}

You can also compile multiple CSS files into a single CSS file using the include tag. When you publish the parent file, the included file is compiled into 1 file with both the parent and child’s CSS, and is minified. This technique is used in the cms-theme-boilerplate’s CSS at the bottom of the file to combine several CSS files into 1 file.

Global Partials

A type of template partial that can be used across multiple templates with content that is edited globally. Global partials are for use with partials using the annotation templateType: global_partial and are often used for headers and footers. This technique is used in the cms-theme-boilerplate for the header and footer partials. These partials are then called in base.html using the global_partial tag. Global partials are a form of global content.

HubL
{% global_partial path="../partials/header.html" %}

Blocks and Extends

When creating complex templates you can create compartmentalized blocks that extend a master template. This technique is not for everyone but can be useful to stay organized when coding complex templates.

One use-case, you can create a master template that includes the required standard_header_includes and standard_footer_includes variables. Within that template, you define a unique block using the following syntax where body is a unique name:

HubL
{% block body %}
        <!-- Default content if template isAvailableForNewContent and chosen as a page template -->
{% endblock body %}
HubL
{% extends "./layouts/base.html" %}
{% block body %}
<h3>Page Content</h3>
<ul>
  <li>Bullet 1<li>
  <li>Bullet 2<li>
  <li>Bullet 3<li>
</ul>
{% endblock %}

This method is used in the cms-theme-boilerplate, in base.html. Which is extended by the templates in the templates folder.

Global Groups

Global Groups created using the drag and drop template builder in the Design Manager, can also be included. The syntax is displayed below:

HubL
{% include "/path/to/global_header.template.json" %}