Key Concepts

This section is designed to help you understand key aspects of the HubSpot Content Management System (CMS) and build great websites on it. To get the most out of this, a professional-level understanding of web development basics, including HTML, JavaScript, and CSS, is expected.

If you’re new to the HubSpot CMS, we suggest beginning with the quick start tutorial and coming back to this when you need it.

How the HubSpot CMS Works

The HubSpot CMS is a SaaS (software-as-a-service) CMS designed to help businesses grow their web presence with a special emphasis on enabling marketers. It’s designed to be used on business websites where non-technical content creators need to be able to build, measure, and iterate on content independently while working within design, style, and functionality guardrails that you as a developer can set up. The content, lead collection, and analytics are also integrated with the HubSpot CRM, making it easy for marketers to create personalized experiences for visitors and integrate those experiences with the rest of the business.

The primary job of HubSpot CMS developers is to work as a content enabler rather than a content creator. Business websites are best when the content is current and optimized. Developers should remove as much friction as possible while establishing guardrails as needed. The HubSpot CMS was designed to balance the needs of developers with the needs of content creators through its module system, flex columns, and drag-and-drop areas. That means less annoying copy-update work for you as a developer and happier content creator users.

Templates and modules are at the intersection between developers and marketers

The key concepts and primitives in the system reflect this philosophy: a well-crafted HubSpot CMS site should be developed in close collaboration with your content creators to understand their needs, and will then require less ongoing support and maintenance from a developer. As you build on the HubSpot CMS, continuously preview how the page building experience looks and feels for content creators. This ensures they can work independently with the site as much as possible.

Animated gif showing user creating a drag-and-drop page

Since HubSpot takes care of hosting and maintaining the CMS, that means you don’t have to worry about plugin management, updates, hosting, scaling, or security. The tradeoff here is that the system puts a few more restrictions on what you can do than self-hosted CMSs. For example, you can’t alter or extend system fundamentals manually or via plugins, manipulate low-level rendering, or access and alter database content directly.

Developer-built content (e.g., themes, templates, modules, JavaScript, and CSS) are created in a developer file system, while page content (pages, blog posts) is laid out and built in a powerful block-based what you see is what you get (WYSIWYG) editor and media files (content creator-built images, PDFs, etc.) are stored in a web app-based file manager.

When a page is rendered, HubSpot routes the request to one of many servers based on domain, renders the page on our servers, and caches it to a content delivery network (CDN) if possible.

Website Pages, Landing Pages, Blogs, and Emails

The HubSpot CMS allows marketers to create several types of content. The user interface (UI) for content creators is slightly different depending on content type. This has implications that developers need to be aware of. 

Templates and modules are associated with one or more of the content types mentioned below. Developers may restrict their use to specific content types.

Website Pages and Landing Pages

Website and landing pages are built independent of one another. Pages are based on templates, and changes can be made either locally to that page as well as to the template. 

The functionality given to content creators is very similar for website pages and landing pages. The distinction between them is that website pages are made to present information that’s part of your website and designed to be found organically, while a landing page is generally associated with a specific marketing offer or campaign (e.g., linked from a marketing email sent to a specific list of contacts). 

In the UI for marketers, the analytics and organization of these page types are also organized separately since landing pages often have specific conversion goals.

Blogs

Blogs in HubSpot CMS, on the other hand, have two views each—one for the listing page and one for the individual post page, then each blog post is populated into each of them. A portal (the term used for an individual instance of HubSpot) can have more than one blog, but the template used for an individual post can’t be specified on a per-post basis. The templates used for the blog listing page and blog post page, as well as the tool to create new blogs, are defined in the HubSpot UI under Settings > Website > Blog.

Emails

The HubSpot Custom (or “classic”) email tool is built on top of the same platform as the CMS, so templates and modules can also be included in emails used with that tool. Emails built with the drag-and-drop email tool cannot use custom templates.

Developer File System

The core assets—templates, themes, and modules, as well as the JavaScript, CSS files, and images that support them—are created in a developer file system which maps to a database behind the scenes. You can see this file system either in the left-hand panel of the Design Manager or in folders synchronized locally using the local development tools. Within the file system, assets can refer to each other with absolute or relative paths.

One thing to bear in mind is that behind the scenes, these files are not stored in that exact way on disk inside HubSpot; they are mapped to entries in a database. This is why access to the developer file system is through the HubSpot CLI tools rather than direct SSH or FTP access, and some file system features you may expect, like permissions and symlinks, are not offered in the developer filesystem.

This differs from the approach of traditional CMSs but means that broken references between file or syntax errors are caught at publish time rather than at runtime, providing you with extra insulation against accidental failures when live traffic is hitting a website.

The CMS will discover the templates in the file system and present them to content creators as they’re making new pages, so the structure of the file system is up to you. There’s no requirement that modules live in a /modules/ folder or JavaScript lives in a /js/ folder. However, we suggest organizing your assets as we have in the boilerplate example code for the CMS. The layout of your assets will look familiar if you’ve worked with other industry-standard development tools.

Themes, Templates, Modules, and Fields

Themes, templates, modules, and fields are the objects you’ll work with most in HubSpot CMS as a developer. Using these different objects effectively lets you give content creators the freedom to work and iterate on websites independently while staying inside style and layout guardrails you set.

Themes and modules contain fields, which are settings of specific data types. (For example, numbers, strings, rich text, images, etc.) Developers can control how these are used in rendering these objects, as well as how they should be organized and appear in the WYSIWYG editor. Content creators can set values for fields in the WYSIWYG editor, which are applied to the theme or module at render time.

Themes

If you’ve worked with other CMSs, the basics of Themes will be familiar to you. Themes are the top-level objects that define the look and feel of a website and create a marketer-friendly content-editing experience. These assets might include templates, modules, CSS files, JavaScript files, images, and more.

Themes allow developers to create a set of fields that content creators use to gain global stylistic control over a website without having to edit CSS. You can specify in CSS where these controls are applied, arrange controls to inherit from others, and manage how they are presented and organized to marketers in the Theme Editor. Content creators use the Theme Editor to modify Theme Fields, preview those changes against existing templates within a Theme, and publish their changes.

These theme fields can be set either globally across a site or overridden at a page level.

Vitality Theme Editor

Templates

Templates define the base markup and style of a set of pages that use a template. They can contain arbitrary HubL, HTML, and links to JavaScript and CSS files, and can be restricted to use with specific content types. You have full flexibility in the markup and style you can include in a template, but you’re encouraged to adhere to a few best practices and use some key features of the CMS to ensure marketers can edit pages easily.

Bear in mind that when you're building templates, you're also building the editing experience for the person who will be creating pages from your templates. This person may be your coworker, or a client, or maybe even you. Either way, make sure the editing experience is easy and intuitive.

This includes:

  • Building templates as part of a theme and using theme-level CSS, including theme fields, to do the majority of styling within a template. This’ll make it easy for content creators to make global and local style changes in a consistent way without needing to get into editing CSS.
  • Using modules (more in the next section on this) for the majority of components on your page, which allows them to be rearranged and reused across a website.
  • Using drag-and-drop areas where possible for core page content, especially on internal pages. Drag-and-drop areas let you set a default layout for the modules that comprise a page but give marketers flexibility to edit layout and style independently.
  • Using global partials to contain shared content like headers and footers that you want to look consistent across a website.

Templates can be built either with HTML + HubL or with a drag-and-drop interface in the Design Manager. If you’re starting a new project, we suggest using coded templates since they give you more workflow options as a developer and support for drag-and-drop areas.

Vitality Homepage Template html

Modules

Modules are reusable components that you can place on templates and pages in the HubSpot CMS. They include controls for marketers and contain HubL/HTML markup, CSS, and JavaScript that together build reusable and editable components of a website.

The controls for a module are defined in fields, so building a great module means considering both the resulting appearance on a page, as well as the editing experience for content editors.

The HubSpot CMS includes common default modules like headers, rich text, images, buttons, and CTAs that you’ll use as fundamental components, but you’ll also likely want to build out elements that can have more interesting layouts that fit into your theme and templates. Some common examples of modules you might want to build are accordions, sliders, and tabbers.

Module form in editor

You can think of a module as an object and modules on pages as instances of that object, meaning updates to the HubL, CSS, or JavaScript of a module are applied across all instances of that module inside pages or templates in a given portal. Modules are also portable across portals, whether you’re using the copy tool built into Design Manager, selling them in the Marketplace, or sharing the code directly with local development tools. This means you can implement a design solution once and use it across pages and portals, and when you need to update it, those changes can be applied across pages without having to edit multiple pages or multiple templates.

Modules may also be included in themes, which allows you to use theme fields to manipulate the look of modules and ensure they’re prominently displayed in the page editor so content creators can have easy access to modules that’ll look great with the designs you’ve built.

For more, see the overview of the Module System.

Fields

Fields are the controls that content creators use to adjust the parameters passed into your themes and modules. Fields are typed, including simple types like boolean, text, URL, choice, and file, but also have more complex fields like font with styling as well as HubSpot-specific fields like links to other pieces of content or forms in the HubSpot system.

Fields can also be placed inside repeaters that’ll pass an array to the module—an example of this could be an image carousel where you want a set of images with associated `alt` text passed in. Rather than creating a number of image and text fields, you can create one of each and put them in a repeating group.

Fields of a module are specified either inside the Design Manager or with this syntax in a fields.json file.  Fields for a theme must be specified in the fields.json file at the root of the theme.

As with the other objects in the HubSpot CMS, pay attention to the editing experience you’re creating as you build out fields in a module or a theme, including how you might want to use field groups to make a clear hierarchy.

The HubL Language

HubSpot’s CMS uses the HubSpot Markup Language or 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. It’s executed completely on the server-side when a page is rendered.

HubL has the features you’d expect of a simple templating language like variables, for loops, and if statements, but also supports more complex rendering macros, data fetching, and mapping with tags, functions, and filters

That said, HubL isn't a programming language. CMSs like Wordpress have a somewhat ambiguous boundary between templating and backend logic. This ambiguity opens the door for a wide variety of approaches to building templates. There are advantages and disadvantages of this flexibility that we won't get into here. As a general rule, the HubSpot CMS is more prescriptive. If you reach the limits of what's possible with HubL, HubSpot provides APIs for creating more customized solutions. CMS Hub Enterprise accounts can leverage serverless functions enabling more sophisticated server side programming. 

As you continue to build on the HubSpot CMS, you can refer to the HubL language reference for more details on specific language features.