Themes

Last updated:

A Theme is a portable and contained collection of developer assets designed to work together to enable a marketer-friendly content editing experience.  Themes and all of the files within themes are designed to be portable between environments and accounts. Themes allow developers to work with coded files, use the tools, technologies, and workflows they prefer, while offering a flexible content creation experience for marketers, supporting layout, style and content updates all within the content editors. 

Themes as a package

Themes being a package cascades throughout the HubSpot app in various places to enable an efficient content creation experience. Developers can use themes to build a design system for content creators to work within. Whatever amount of flexibility, or guardrails can be built into a theme to meet the needs of your business. 

Page creation

When content creators start building new pages, they are prompted to start by selecting which theme they are building a page from, followed by selecting which template within the theme to use.

Theme selection inside of HubSpotThis helps content creators easily distinguish between templates for various sites (or themes) you have within a single HubSpot account and keeps the page creation process organized. The screenshot, as well as other configurations for a theme, are set in the theme.json file. 

Theme fields

Themes allow developers to create a set of Theme Fields, similar to Module Fields, which allow content creators to tweak various knobs and dials designed by a developer to allow global stylistic control over a website without having to edit CSS. Developers use HubL to access the values of Theme Fields throughout their CSS. Content creators use the Theme Editor to modify Theme Fields, preview those changes against existing templates within a Theme, and publish their changes.

themes

Theme fields are dictated by the fields.json file of a theme. 

Theme modules

The modules within a theme should be designed specifically for use within templates in that theme. The content editor will emphasize these theme modules, making it quick and easy for content creators to add modules to the pages they are building that are designed to work well in the context of that page. Default modules and the rest of the modules in your HubSpot account will still be available.

Theme modules inside of a theme

Theme file structure

A theme is a single directory of files. You can include HTML, CSS, and Javascript files, modules and additional files that can be organized in any manner within subdirectories of the parent theme folder. Two JSON files are necessary to build a theme, theme.json and fields.json, which should be included at the root theme folder.

To start from an example, see the HubSpot CMS Boilerplate.

theme file structure

At this time .json files can only be created and uploaded to a HubSpot account through the local development tools.

theme.json

The theme.json file contains the meta-information for your theme directory, such as the themes readable label, its preview screenshot and various configurations for how the theme should behave. Your theme.json file will look something like:

JSON 
// theme.json
{
    "label": "Cool Theme",
    "preview_path": "./templates/home-page.html",
    "screenshot_path":"./images/templates/homepage.jpg",
    "enable_domain_stylesheets": false,
    "version":"1.0",
    "author":{
      "name":"Jon McLaren",
      "email":"noreply@hubspot.com",
      "url":"https://theme-provider.com/"
    },
    "documentation_url":"https://theme-provider.com/cool-theme/documentation",
    "license":"./license.txt",
    "example_url":"https://theme-provider.com/cool-theme/demo"
}
theme.json
ParameterTypeDescription
label
String

The readable label of the theme, used in various places the theme is shown throughout the HubSpot app, like the template selection screen and the theme editor. 

preview_path
String

A path, relative or absolute, to a template file in the theme which should be the default template, used when previewing a theme in the theme editor. 

screenshot_path
String

A path, relative or absolute, to an image file that is used to give a snapshot of what the theme looks like in various places theme selection occurs, such as in the template selection screen. 

enable_domain_stylesheets
Boolean

Enabling or disabling stylesheets attached to domains in Website Settings getting included on templates within the theme. The default value is false.

version
String

Integer version number supporting . versions.

Author
object

Object to provide information about yourself as the theme provider.

name
The provider's name.
email
The provider's support email address.
url
The provider's website.
documentation_url
String

The theme documentation link.

example_url
String

The theme live example link.

license
String

A valid SPDX Identifier or the relative path to the license within your theme.

This license dictates what use and modification is permitted by the creator of the theme. Useful when submitting to the marketplace.

fields.json

The fields.json file controls the available fields and field groups in the theme editor. The ability to access the theme editor and these fields are controlled by the "Edit global content" Marketing user permission. You as the developer have full control over the fields available to tweak, base the fields you will supply based on the end users. A marketplace provider for example may want to provide a very flexible set of options, whereas another developer may want to limit what options are available.

Fields available for use in themes are:

For comprehensive documentation on the possible options for theme fields, see the module and theme fields documentation. 

The fields available for themes are intentionally limited versus what is available for modules. In general, theme fields are best for CSS related tweaks, and global content is better for actual content.  This is to encourage practices that are good for content creators.

Example problem: Your company has a tagline. You would consider it to be part of your branding.

Problematic solution: You might think to add it to the theme fields, where all of your branding goes.

This results in an experience where content creators can't edit the tagline from the content editor and have no idea why. Instead they need to go to the theme editor.

Better solution: Use a global module, the global module could be placed inside of global partials, like your header or footer. Enabling you to have 1 place to edit the content across all of the places it lives. 

The content creator can easily highlight and directly edit this content being aware it is global.

Using theme field values

To access field values, use dot notation and prefix the path to the value in fields.json with theme. You can use a themes fields value in your stylesheets using syntax like {{ theme.path.to.value }}. For example, the font field outlined below:

JSON 
// fields.json
[{
   "type": "group",
   "name": "typography",
   "label": "Typography",
   "children": [
     {
       "type": "font",
       "name": "h1_font",
       "label": "Heading 1",
       "load_external_fonts": true,
       "default": {
         "color": "#000",
         "font": "Merriweather",
         "font_set": "GOOGLE",
         "variant": "700",
         "size": "48"
       }
     }
  ]
}]

Would be referenced in CSS with:

CSS 
h1 {
 font-size: {{ theme.typography.h1_font.size }}px;
 font-family: {{ theme.typography.h1_font.font }};
 color: {{ theme.typography.h1_font.color }};
 text-decoration: {{ theme.typography.h1_font.styles.text-decoration }};
 font-style: {{ theme.typography.h1_font.styles.font-style }};
 font-weight: {{ theme.typography.h1_font.styles.font-weight }};
}

Previewing themes

For developers sometimes you need to be able to test out that your theme fields are working properly but don't want to impact real pages. That's where theme test mode comes in.

Test mode

Test mode gives you a safe environment to be able to play with your theme's fields and ensure they are working as you expect. The interface looks exactly like the theme preview/editor that content creators can see, however you can rest assured that you are not changing your actual website's settings. To protect against accidental theme setting updates, publishing is blocked in test mode. You can tell if you are in test mode as ?testmode=true appears in your address bar, and a test mode icon will display in the header of the theme editor.

Theme Test/Preview Mode

How to enable theme test mode

  1. In the Design Manager, select your theme in the Finder.
  2. A preview button will appear. Select it and you will now be in test mode for your theme settings.

Another method is to open your theme settings from within the page editor. Then once inside add the query parameter ?testmode=true to the URL in your address bar.

Related resources