Last modified: August 22, 2025
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 above template is the base.html template included in the HubSpot CMS boilerplate, which is a great way to get started developing with HubSpot.

​
Familiarity and tooling

Since HTML + HubL templates are coded files, you can use your preferred tools to edit them locally. It’s recommended to use HubSpot’s own local development tools so that you can upload, fetch, watch, create and otherwise securely manage files in the developer file system as well as the file manager. Building HTML + HubL templates with HubSpot is similar to using other templating language you may have used before. 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 takes much of the maintenance and performance optimization work off of the developer. For example, if you want to load CSS file on a page for certain modules, instead of using <link rel="stylesheet" type="text/css" href="https://developers.hubspot.com/docstheme.css">, you should include the stylesheet through css_assets in the module’s meta.json file. This enables HubSpot to conditionally load the CSS only when the module is present on a page, minimizing the amount of unnecessary CSS loaded. Learn more about optimizing your HubSpot development workflow.

​
Template annotations

Template annotations, included at the top of a template, configure important template settings, such as the template type and whether it can be used to create new content. Template annotations can be changed at any time during the development process. Below, learn more about available template annotations. 
<!--
  templateType: page
  isAvailableForNewContent: false
  enableDomainStylesheets: false
  label: Homepage
  screenshotPath: ../images/template-previews/home.png
-->

<!doctype html>

<html>
  ...
</html>
AnnotationTypeDescription
templateTypeStringSpecifies which template type a file is. Values include:
isAvailableForNewContentStringSpecifies if a template is available for selection in the content creation process. Values include: true, false.Templates set to false do not need to include the required variables. Templates of the page type that are set to false can also be used as standard partials.
enableDomainStylesheetsStringSpecifies if the template should load domain stylesheets. Values include: true, false.
LabelStringUser-friendly description of the template, displayed in the template selection screen. For example, About Page, Homepage, Pricing.
screenshotPathStringThe screenshot to display when a content creator is selecting a template. This screenshot should make it easy to differentiate between your templates.
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. Partials enable you to take a more modular approach by sharing markup between multiple templates. For example, a header can be made into a partial so that you can easily include it as a component without needed to code it again.

​
Standard partials

A standard partial is a reusable template or component containing content that can be edited on individual pages. This enables content creators to change the content as needed, as opposed to global partials which always share content. For example, the following code would pull the sidebar module into another template file. Standard partials must include the following annotations at the top of the template file:
  • templateType: page
  • isAvailableForNewContent: false
{% include "../partial/sidebar.html" %}

​
Global partials

A global partial is a type of global content that can be used across multiple templates with content that is shared across all instances of the partial. Global partials are often used for headers and footers, which you can see an example of in the HubSpot CMS Boilerplate header and footer. These partials are then called in base.html using the global_partial tag. Global partials must include the annotation templateType: global_partial at the top of the file. 
{% global_partial path="../partials/header.html" %}

​
Blocks and extends

When creating complex templates, you can create compartmentalized blocks that extend a parent template. For example, you can create a parent 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: 
{% block body %}
<!-- Content to display -->
{% endblock body %}
Then, in the child template, you can extend the parent template, then insert more content into the body block. 
{% 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 base.html template of the HubSpot CMS boilerplate, which then is extended by the other 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: 
{% include "/path/to/global_header.template.json" %}