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.
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.
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.
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.
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.
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 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 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.
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.
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
/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 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 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.
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.
- 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.
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.
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 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.
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.