Developer Guide - Best Practices for Customizing a HubSpot Theme

Introduction

Before being able to customize a HubSpot theme, you need to create a child theme.
Creating a child theme in HubSpot allows for customization while retaining the ability to receive updates from the parent theme. In HubSpot, it is not possible to edit files for themes purchased from the asset marketplace. While it is possible to build your website using the original marketplace/parent theme, using a child theme is a future-proof way of building your website in CMS Hub.
This guide outlines what a child theme is, its importance, and best practices for working with child themes.

What is a Child Theme and Why is it Important?

A child theme in HubSpot is a sub-theme that inherits the functionality and styling of the parent theme, allowing for customizations without altering the original files. This ensures that updates to the parent theme do not overwrite your customizations, providing a safe and organized way to manage website modifications.

How to Setup a Child Theme?

For detailed instructions on how to install a child theme, refer to the Maka Agency's Guide on Creating Child Themes.

Always ensure that your desired customization isn't achievable using the theme's existing features or HubSpot CMS's standard functionality (Theme Features and Documentation).
Explore alternative solutions and consider reaching out to the theme authors via support for assistance. This not only helps you find a solution but also provides valuable feedback to the authors, potentially improving the theme for everyone.

How to Add Custom CSS and JavaScript

Add custom styles to the child.css file and custom JavaScript code to the child.js file. Both are located in the root folder of your child theme. The files might be named differently during child theme creation.
Ensure that your POWER child theme’s styles have the highest priority by correctly setting the order in the base.html file.

TIP: If you want to change the styles or functionality for a specific module or set of modules, you can use the Custom Class feature. All of our modules include a field where you can add one or several custom CSS classes. This allows you to target those modules specifically in your child.css or child.js file for custom styling or functionality.

TIP: If you would like to hide an existing element, you can target it with a suitable CSS selector and use display: none; instead of removing it from the HTML structure.

If you would like to add an element, consider using the CSS pseudo selectors :before or :after.

Avoid cloning the parent theme’s CSS or JS files or even folders to the child theme; only add the necessary custom code via child.css and child.js

Overwriting Theme Assets

When necessary, overwriting can be done using the context menu > "Clone To Child Theme" on parent theme assets in the Design Tools.

Cloning modules or templates to the child theme is not necessary to use them. The child theme will automatically include the original and up-to-date modules/templates unless they are cloned to the child theme.

Assets with the same name and path will replace the parent theme’s asset, applying customizations site-wide for existing content. For modules and templates, we recommend using unique naming conventions instead to create custom versions that coexist with the original, ensuring at least the original can still receive updates.

Cloning assets to the child theme is generally to be avoided. This practice detaches the assets from updates to the parent theme.

This can potentially lead to compatibility issues with future theme updates, which might break live-page content. Additionally, theme updates cannot be reverted
Code is isolated from maintenance by the theme developer (performance improvements, browser compatibility updates, general bugfixes, improved responsiveness)
New Features made by the theme developer will not be available in child theme modules

With our POWER THEME, we strive to maintain downward compatibility as much as possible. However, there are instances where we need to introduce breaking changes, which may require custom code to be adapted or updated to stay compatible. Please ensure you register for our product newsletter to stay informed about such changes. Additionally, you can also check out our changelog before updating the theme.

Overwriting a theme module

Overwriting a theme module is advisable only if you need to extend/change the module's field structure or HTML structure in ways a simple JavaScript code cannot accomplish.

Tip: For custom CSS and JavaScript refer to "HOW TO ADD CUSTOM CSS AND JAVASCRIPT".

Tip: If you intend to connect a theme module to HubDB data, contact us for assistance. We can help you achieve this without needing to clone the module to the child theme.

To clone a module to the child theme follow these steps:

Open the Design Tools via Content > Design Tools
Locate POWER's original marketplace theme in the folder @marketplace → maka_Agency → POWER THEME
Find the module you want to customize in the modules folder
Right-click, select "Clone to Child Theme," and choose the child theme
Navigate to the child theme, rename the module's filename with a unique naming convention
Also, update the module label for easy identification in the page editor
Add your customizations to the HTML structure or module fields
Include the current theme version and notes about your changes in a comment at the top of the module.html file

Your custom module can now be drag-and-dropped into your page.

Tip: If you want your changes to affect existing content built with the original module, skip renaming the file. Be aware that this will overwrite the original module.

Overwriting a theme template

Building templates as base for website pages not problematic if they use HubL dnd_module statements that reference theme modules via the path parameter.
Existing theme templates can be used as a base (code), code can be generated via developerMode.
But sections are also a great alternative.
As soon as templates contain HTML code that uses classes and structure of the theme, then it should be avoided.