Building a site on HubSpot CMS
What the platform gives you, what a theme adds on top of it, and the order to do things in so the site is still editable by a marketer a year after launch.
What HubSpot CMS gives you before any theme
The parts that are already there
A portal comes with page hosting, forms, a blog, contact records and a page editor. What it does not come with is a design. Every page you create starts as an empty drag-and-drop area, and every module you drop into it is styled by whatever theme is active.
- Pages and landing pages, each built from a template
- A blog with listing and post templates
- System pages: error, password prompt, subscription preferences
- Forms, and the contact record every submission lands on
- Theme settings, which is where a theme exposes its colour and type controls
What a theme is, in file terms
A theme is a folder you upload to the portal. It holds templates, modules, stylesheets and a settings definition. Once it is uploaded, a page created from one of its templates renders through it, and the settings appear in the theme editor.
Deciding what the site is before you open the editor
Count the page types, not the pages
Most sites have between six and a dozen genuinely different page shapes and then many instances of each. A services page and a product page may look like two problems and turn out to be one template with different content. Work out the shapes first: it decides how many templates you need and how much of the build is content entry rather than development.
Decide who edits what
This is the decision that determines whether the site survives. A value that lives in a module field can be changed by a marketer in the page editor. A value hardcoded in a template can only be changed by someone who can upload files. Anything a marketer will plausibly want to change in the first year belongs in a field.
Write the content before the layout
A layout designed against placeholder text breaks on the first real headline. Draft the actual words, including the longest name in the database and the shortest paragraph anyone will write, and design against those.
Setting up the theme
Presets first, then the individual settings
A preset switches the palette and the type pairing for the whole site at once. Pick the preset closest to where you are going before you start changing individual values, because a preset changes the tokens that everything else is derived from.
Change a token, not a rule
Colour, type, spacing and radius resolve to CSS custom properties. Changing a setting changes the property, and every module reading it moves at the same time. Writing a colour into one module instead sets that module adrift from the rest of the site the next time the palette changes.
Set the container width once
The container width is a theme setting, and sections, heroes and the navigation all measure against it. Change it there and the whole site re-measures together.
Building the pages
Start from a template, then a section, then a module
A page template is a whole page shape. A section is a reusable block you drop into a drag-and-drop area. A module is one component. Reach for the largest one that fits: rebuilding a page out of individual modules when a template already exists is the most common way a build runs long.
One h1 per page
The hero carries it. Every section heading below it is an h2, and the cards inside a section are h3. A card grid placed directly under the hero jumps from h1 to h3, which is the most common heading defect on a marketing site and it is invisible until someone measures it.
Fill the sections that carry an ask
A closing band with a heading, one line and a button in a large panel reads as unfinished. If the band has nothing to say beyond the heading, the page does not need the band.
Handing it over
What to write down
Two lists. The theme files you changed, because an update replaces them. The settings you moved away from the preset default, because that is the difference between the site and a fresh install.
What to walk them through
- Creating a page from a template and publishing it
- Editing a module in the page editor and what each field does
- Where theme settings live, and which of them move the whole site
- What to do when something looks wrong: which change to undo first
The test that the handover worked
Someone on the client team ships a change without asking you. Until that has happened once, the handover is not finished.
To upload one, yes, or someone comfortable with the HubSpot CLI. After that, no. Page content and module settings are edited in the page editor, and colour and type are edited in theme settings.
Yes. Two things follow from it: a file you changed is replaced when an update lands, so keep a list of which ones you touched; and a module you write from scratch against the theme tokens is yours rather than the theme author’s.
Pages are tied to the template they were created from. Switching themes does not re-point them; you create pages from the new theme’s templates and move the content across. Plan for that rather than discovering it.
In theme settings, once. If the same colour is typed into four modules, the next palette change is four edits and one of them will be missed.
Fewer than the page count suggests. Group pages by shape rather than by subject, and most sites collapse to a handful of templates with a lot of content behind them.
Pick the preset, set the container width, and create one page from one template and publish it. Getting a single page live before building anything else surfaces portal and domain problems while they are still cheap.
The pages this guide builds towards.
Each stage in the guide ends with a page you can open here. If a step is unclear, the finished version of it is one click away.
Count the shapes
How many genuinely different page types, and who will edit each one. This decides the template count.
Set the tokens
Preset first, then the individual settings, then the container width. Never a colour written into a module.
Build one page
One real page, published, before anything else. Portal and domain problems are cheap on day one.
Write the two lists
Files you changed and settings you moved. Those two lists are the handover.
More on building with the theme
Shorter pieces on single parts of the build.
The theme this guide was written against.
Everything above is how the build goes. Studio Nope Official is the folder that removes most of the first half of it.
- check_circle Templates for every page type in the guide
- check_circle Colour and type live in theme settings, so one change moves the site
- check_circle Documentation written for the person who inherits it
Read the documentation before buying. It is public and it is the whole thing.