The HubSpot CMS Boilerplate

Last updated:

The HubSpot CMS Boilerplate serves as a starting point for helping developers get a website up and running quickly on the HubSpot CMS while illustrating best practices developers can use when building on the HubSpot CMS Platform. The boilerplate is an open-source GitHub project where all are welcome to suggest changes and fork for their own use. If you are new to the HubSpot CMS, and want to get started on a new project based off of the boilerplate, follow the quick start guide to developing on the HubSpot CMS.

Why should developers use the HubSpot CMS Boilerplate?

The HubSpot CMS Boilerplate is built and actively maintained by HubSpot. When building the boilerplate, we incorporated best practices that were influenced by how developers created the best website building experience and then applied those to building a website on the HubSpot CMS. This provides developers with a clean, optimized, and ready to modify website that saves developers a significant amount of developmental time. The boilerplate also provides comprehensive CSS for HubSpot related assets such as forms, menu modules, base classes and more. You can view a live demo of the boilerplate in action by visiting https://boilerplate.hubspotcms.com/

How to get started using the HubSpot CMS Boilerplate

To get started with using the boilerplate in your local development environment, simply follow our Getting Started Developing Websites on the HubSpot CMS guide.

HubSpot CMS Boilerplate structure

Developers can work with the boilerplate using local development tools or directly inside of the Design Manager. The boilerplate uses relative path references for all of the assets which makes it easy to adapt to whatever your project may be. This also allows for the boilerplate to be completely portable between accounts on the HubSpot Platform. Below is a screenshot of the folder structure of the boilerplate’s assets. The boilerplate silos its assets into multiple directories for easy identification of where they reside.

Folder Structure of the HubSpot CMS Boilerplate

The HubSpot CMS Boilerplate’s underlying template structure revolves around a common base layout, located in the templates > layouts folder, that is then extended when creating additional page templates inside of the system using the {% extends %} tag and referencing the {% block body %} block for its main content. A sample of how the extend tag and blocks are being used can be seen in any of the html files inside of the templates directory.

This is a common method of developing on CMS systems where you have a base (sometimes called a master) template that contains all the main common structural pieces of content on your site. These are often items that are inside of the <head> element on your site such as common meta properties (ex: Title and Meta Description), Favicon links, CSS links, and 3rd party scripts

HubL
<!doctype html>
<html lang="{{ html_lang }}" {{ html_lang_dir }}>
 <head>
   <meta charset="utf-8">
   <title>{{ page_meta.html_title }}</title>
   {% if site_settings.favicon_src %}<link rel="shortcut icon" href="{{ site_settings.favicon_src }}" />{% endif %}
   <meta name="description" content="{{ page_meta.meta_description }}">
   {{ require_css(get_asset_url("../../css/layout.css")) }}
   {{ require_css(get_asset_url("../../css/main.css")) }}
   {{ require_css("https://fonts.googleapis.com/css?family=Merriweather:400,700|Lato:400,700&display=swap") }}
   {{ require_js(get_asset_url("../../js/main.js")) }}
   {{ standard_header_includes }}
 </head>
 <body>
   <div class="body-wrapper {{ builtin_body_classes }}">
     {% block header %}
       {% global_partial path="../partials/header.html" %}
     {% endblock header %}
 
     {% block body %}
       <!-- Nothing to see here -->
     {% endblock body %}
 
     {% global_partial path="../partials/footer.html" %}
   </div>
   {{ standard_footer_includes }}
 </body>
</html>

Inside of this base layout, there are also calls to our global header and footer partials. This allows us to be able to keep the code for these partials in their own separate files for modularity and, because they are global partials, can then be easily edited using our Global Content Editor by your content creators.

jQuery

The HubSpot Theme boilerplate doesn't require jQuery in order to function. For older HubSpot accounts jQuery is loaded by default. Newer HubSpot accounts have jQuery disabled by default.

Historically HubSpot scripts required jQuery to function properly, so the domain-wide setting was there to help ensure compatibility. HubSpot scripts no longer use jQuery. Because JQuery is not required, and there are better ways for developers to include libraries that also work with source control. It is advised to disable the jQuery settings for new websites. 

Be aware if disabling jQuery on a domain that has an existing website - any landing pages or existing web pages you may have could break if they depend on jQuery.

If you wish to use jQuery on your new website it is recommended that you use the latest version of jQuery. There are two easy ways to do that:

  • Upload the latest version of jQuery to your developer file system and use require_js to load it where and when you need it.
  • Use a CDN you trust, and use require_js to load jQuery where and when you need it.