Last updated:

Templates are reusable page or email wrappers that generally place modules and partials into a layout. A template or group of templates can be part of a Theme. Inheriting styles and settings from the theme enables a unified appearance. Templates contain references to stylesheets, JavaScript files and other assets used throughout a website or email. Pages, landing pages, blogs, system pages, and emails on HubSpot all use templates.  When content creators create a page or email, they select a template to use before populating it with content. 

Templates live inside of the developer file system. The same system you see in the finder inside the design manager and can access using the Command Line Interface (CLI). Not to be confused with the File Manager, which is a file system used by content creators on HubSpot to store assets such as images, videos, and PDFs. This separation enables developers to store their files in a safer place without worrying that a content creator may accidentally break something by moving or deleting a file.

HTML + HubL and Drag and Drop templates

Templates can be created by uploading them to HubSpot using the local dev CLI, or created directly in the Design Manager.

Create a template using the Local Development CLI

To create a template using the CLI you must first have it installed and configured. Once you do, you can create a template using:

Shell script
hs create template <name> [dest]
hs create template parameters

Custom name of the template you are creating.


A local path to directory you want to create this template in. This argument is optional. If ommited this argument will default to your current working directory

After creating the template the asset is created locally. You will need to upload the asset to your account before it is reflected in the developer file system and template selection screens. You can also use the watch command to automatically upload all new files and edits to existing files in the current working directory and child directories.

Create a template using the Design Manager

The Design Manager uses the same developer file system in which your templates, layouts, modules, javascript, CSS, and other production assets live. 

To create a new template, navigate to Marketing > Files and Templates > Design Tools. This is the Design Manager. In the finder (the leftmost pane) click File > New File.

Design Manager UI showing New file dropdown

Choose "HTML & HubL" or "Drag & Drop".

Follow the prompt after to select the template type.

Template Types

Templates can be used for different types of content. In HTML + HubL templates, you can designate the type of template using a simple comment annotation at the top of your .html file. For drag and drop design manager templates, you set the template type only at creation, it cannot be changed later without converting to HTML +HubL. Drag and drop templates do not use template annotations.


When creating a blog, blog templates are similar in structure to standard page templates. The crucial difference is that they can be selected in content settings as blog templates whereas page templates cannot. Templates created with blog_listing, blog_post, or blog, templateType do not appear when a user is creating a web page, in the template selection screen. Blog templates actually have two forms, blog listing pages and blog post detail pages. 

Blog listing

The blog listing template is the template users will see when navigating to the blog's URL. Typically this template is used to list summaries, titles and featured images of all of the posts on the blog, additionally typically displays pagination to get to older posts.

templateType: blog_listing

Blog post

The blog post template, is the template users will see when viewing an individual post in the blog. These templates typically show the full post content.

templateType: blog_post

Combined blog post and listing template

A single blog template can handle the layout for both listing and detail pages but more typically these are separated into separate templates. Combined templates will show in the blog settings as selectable for both listing and blog post options. If you are creating a template that is intended to only be used for posts, or listings, you should use blog_post, or blog_listing, instead.

templateType: blog

For a simpler development and content creator experience it is recommended to use the separate blog_post, and blog_listing templateTypes instead of combined templates.


Email templates are used by the email tool. They have the most stringent set of requirements since they need to be viewed in many different email clients and conform to best practices to ensure proper deliverability. Both HTML + HubL and design manager drag and drop email templates come pre-populated with baseline components upon creation. Templates with this templateType are only visible for template selection when creating an email.

In order to stay CAN-SPAM compliant, email templates have a set of required variables that must be included.

Email templates also have a built-in functionality to inline-css added to <style> elements with a special class name or data attribute. Inlining CSS in emails is a method used to get better support across email clients. Fortunately, most of the popular email clients now support embedded css, that however is not representative of your specific recipients. Use good judgment to do what is right by your recipients.

Learn more about building email templates.

templateType: email


Page templates are the most open-ended template type. They can serve as any flavor of web page or landing page. Page Layouts are not pre-populated with any components. Coded page templates come pre-populated with sparse markup including suggested HubL tags for meta info, title, and required header/footer includes. Examples of pages that would typically use a page template would include but are not limited to:

templateType: page

System Pages

System page templates are flagged internally for their specific purpose. In Content Settings, you can select these templates for their specified purpose in the system tab.

Error Pages

Error pages can be set in Content Settings as either 404 or 500 pages. Both templates use the same templateType. Templates created with this templateType do not appear when a user is creating a web page, in the template selection screen.

templateType: error_page

Email Subscription Preferences

The email subscription preferences page. Lists all of the available subscription types a user can opt into or out of. Required to contain the {% email_subscriptions "email_subscriptions"  %} HubL Tag. See the subscription preferences template in the cms-theme-boilerplate.

templateType: email_subscription_preferences_page

Email Backup Unsubscribe

A system template for email unsubscribe pages. Required to contain the {% email_simple_subscription "email_simple_subscription" %} HubL tag. See the email backup unsubscribe template in the cms-theme-boilerplate.

templateType: email_backup_unsubscribe_page

Email Subscription Unsubscribe Confirmation

A system template for email unsubscribe confirmation pages. This is where users are sent when they go to the URL generated by the {{ unsubscribe_link_all }} variable.  See the subscription confirmation template in the cms-theme-boilerplate.

templateType: email_subscriptions_confirmation_page

Password Prompt

Password prompt templates provide a branded page content creators can display to require a password before a visitor can view the page’s actual content. Password prompt templates are set via Content Settings. How to make a page on HubSpot password protected. See the password protected page prompt in the boilerplate.

templateType: password_prompt_page

Search Results Page

A system template for the built-in CMS site search listing functionality. See the search results page template in the boilerplate.

templateType: search_results_page


HubSpot accounts with the memberships functionality (CMS Hub Enterprise) can create pages on their sites that only users apart of specific lists in the CRM can access. This enables site visitors to have accounts with login credentials. These templates give you control over the appearance of these pages.

Only HTML + HubL templates can be membership templates.

Membership Login

This is the login page that displays when a user tries to access content that is access controlled through the memberships functionality. Typically contains the {% member_login "member_login" %} module. See the example membership login template in the boilerplate.

templateType: membership_login_page

Membership Register

This is the user registration page that allows users to create an account to view the content that users of this list can access. Typically contains the {% member_register "member_register" %} HubL Tag. See the example membership registration template in the boilerplate.

templateType: membership_register_page

Membership Password Reset

This is the password reset page. Users provide their new password on this page. Typically contains the {% password_reset "password_reset" %} HubL Tag. See the example membership password reset template in the boilerplate.

templateType: membership_reset_page

Membership Reset Request

This is the request a password reset page. Displaying a form to request a password reset email. Typically contains the {% password_reset_request "password_reset_request" %} HubL Tag. See the example membership password reset request template in the boilerplate.

templateType: membership_reset_request_page

Previewing Templates

You should always check your work after updating templates to ensure they look and function how you intend. HubSpot’s Design Manager provides a tool for previewing modules and templates. To preview a template open the template in the design manager, in the top bar click “Preview”.

Design Manager preview with display options dropdown

For most templates, the preview will show the default state for the template - the same state you would see if you created a Website Page from the template but did not edit it. There are two preview modes for templates “Live preview with display options” and “Live preview without display options”. 

Live preview with display options displays the page within an iframe, giving you some tools you can use for testing responsiveness and seeing how domain stylesheets may impact your template.

Live preview with display options shown

Blog templates are unique in that because you need a blog listing and blog posts to really get a sense for how the template is working. The preview for the blog lets you pick an existing blog to populate the preview with it’s content. From there you can choose to view the listing or detail page for that blog template.

Live preview with display options for blog

Previewing the templates using the template previewer alone may be good for minor visual tweaks. When changing drag and drop areas, default parameter values on modules, or other significant changes, it’s best to create a website page, blog, blog post or email, using the template. You can then try out different module field values and test what your template will look like in the real world and optimize for the best content creator experience. 

You can use content staging, a draft preview, or your developer sandbox account to view the page without worrying about the page being live for the world to find and see.

Included CMS files

There are certain JavaScript and CSS files that are attached to CMS templates. Some files are automatically included and cannot be removed, while others can be optionally included. To learn more about the order in which stylesheets are attached to CMS content, check out this article.


jQuery is optionally included in the head tag of HubSpot templates. If included, it is rendered as part of the standard_header_includes HubL variable.

 In Settings > Website > Pages you can change the jQuery  version to 1.11.x, version 1.7.1, or disable it completely. You can also choose to include a jQuery migrate script for backward compatibility with older browsers. You can move jquery to the footer, to improve page performance. Moving jQuery can break javascript relying on it. To test your site add ?hsMoveJQueryToFooter=True to the end of your URL while viewing the most important pages of your website, to ensure nothing breaks.

jQuery was historically included by default because HubSpot functionality previously required it. CMS Hub does not require jQuery. Most of jQuery's functionality now has modern vanilla javascript equivalents, and we encourage using them. If you need to use jQuery, we encourage disabling the default version in settings and using the latest version loaded above the </body> tag.

To test if removing jQuery on your site will break anything, add ?hsNoJQuery=true to the end of the URL while viewing multiple pages of your site especially those with heavy interactivity.


Layout.css (formerly known as required_base.css) is the file that is responsible for styling HubSpot's responsive grid. This file is always automatically included in any drag and drop template. It is not included by default in custom coded templates. For developers utilizing dnd_area tags in coded HTML + HubL templates you do not need to load the layout.css file, but a version of it is included in the cms theme boilerplate to make it easier to get up and running quickly.

In addition to the responsive grid CSS, the file includes some classes that can be used to show and hide elements at different viewports. You can view the file, here.

HubSpot Tracking Code

The HubSpot tracking code is always automatically added to any HubSpot template (excluding email templates). It is included with the standard_footer_includes HubL variable. The tracking code loads an analytics JavaScript file named your_HubID.js (example 158015.js). This tracking code is directly integrated with HubSpot's GDPR functionality.

Avoid hard-coding text into your templates

When building your templates use modules with fields whenever possible for text. This not only makes it possible for content creators to update and change text, it makes it possible to localize later.

Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.