Skip to content

Theme baseline#

On day one the repo becomes the source of truth for the theme. Fetch the published theme from the live portal, commit it untouched, and tag that commit as the production baseline. Every later diff is measured against it.

In Claude Code

The hubspot-site-setup skill of the bb-hubspot plugin covers the fetch, the baseline tag and standing up the dev portal. The templates it copies are in the plugin's templates/ folder.

Fetch and tag#

hs cms fetch "<Theme Name>" <theme-folder> --account <client>-live
hs cms fetch "<Other>/fonts" fonts --account <client>-live      # only if the theme loads assets from another folder
git add -A && git commit -m "Initial import of the live theme" && git tag prod-baseline

A common case for the second fetch: the theme's fonts.css loads fonts from a sibling folder outside the theme.

Look before you build#

  • Templates. Find the page templates and check that each one is already a chassis: a base layout with a single drag-and-drop area. The first site had five (light, dark, dark header, dark footer, empty), each with one dnd_area, so no chassis templates needed writing. Note the dnd area's name (often main_content): it goes into hubspot-site.json as dnd_area, and the Pages API needs it.
  • HubDB ids. Search the modules for hard-coded HubDB table ids. A module that points at a table the test portal doesn't have fails upload validation, so move it aside for test uploads.
  • External assets. Note everything the theme loads from outside its own folder (fonts, shared images, other themes' CSS). Each of those folders has to exist on every portal the theme runs on.
  • Module ids. Every module's meta.json carries a module_id. It is the same on every portal, so one id map serves dev and live.
  • The reference module. Pick the module whose fields and Style tab are the best-structured. It becomes the shape that the rebuilt modules follow. On the first site that was the card module.

Stand up the dev portal#

Only once the client says go:

  1. Upload the untouched theme and any external asset folders to the dev portal.

    hs account list
hs cms upload <theme-folder> "<Theme Name>" --account <client>-dev

  2. Recreate the navigation menus from the live header and footer trees. Capture the live trees as fixtures in tools/fixtures/ first; they also feed the preview site. Menus can be created over the API (see HubSpot facts).

  3. Build one smoke-test page through the Pages API. It proves that the dev key has the content scope, and it becomes the sentinel page that the publisher checks before every write.

Global content is manual

Some settings, such as which menu the footer's global module uses or a header button, can only be changed in the portal UI. List them under a Pending UI steps line in CLAUDE.md so they don't get lost.