Skip to content

HubSpot Site Workflow#

This is how Brightbase takes over a live HubSpot CMS site and builds new pages and modules on it without risking the live portal. Each client site gets one git repository, and that repo becomes the source of truth for the theme. A read-only crawl of the live site produces written design rules. Every module gets a generated catalog and a local preview page. New pages are built from copy docs as local drafts and reach HubSpot only through a disposable test portal.

The process came out of a real site takeover and is packaged as the bb-hubspot plugin for Claude Code: skills for each stage, a guard hook, and the scripts. These pages describe it in general terms, with real numbers and real mistakes wherever they make the point.

What you end up with#

Artifact What it gives you
The theme in git Every module, template and stylesheet, fetched from the live portal and tagged as the production baseline.
A crawl report The section and module makeup of every live page: the evidence for every rule that follows.
Design rules Page archetypes, light/dark rhythm, and which module to use for which shape of copy, written by hand from the crawl.
A module catalog Every module's fields, defaults, CSS hooks and live usage count, generated from the theme.
A preview site One local page per module, rendered from the module's real module.html, with the settings behind each example.
A page pipeline Copy doc → annotated HTML draft → automated QA → a page on the dev portal → a draft on live.
A regression gate Before/after snapshots of every live page around any module upload to production.
A dated log CLAUDE.md records every upload and publish, so you can always say what is on which portal.

The pipeline#

flowchart TB
  live[Live site<br/>read-only]
  live -- crawl-site.py --> report[site-crawl.md] --> rules[DESIGN-RULES.md<br/>by hand]
  live -- hs cms fetch --> theme[theme/] --> cat[build-catalog.py<br/>build-previews.py] --> modules[MODULES.md<br/>drafts/previews/]
  live -- export-copydocs.py --> copy[imports/slug.md]
  rules --> gen
  modules --> gen
  copy --> gen[build-page.py] --> draft[drafts/slug.html] --> qa[qa-draft.py]
  qa -- client go --> pub[publish-page.py] --> dev[Dev portal<br/>create + publish]
  dev -- regression gate --> liveout[Live portal<br/>drafts only]

Nothing writes to the live site except at the bottom, and even there a script only ever creates a draft. A person publishes it.

Principles#

The live portal is read-only by default. Crawl, fetch and read freely. Writes to production are rare, deliberate and draft-only, and the tools refuse anything else. See Accounts and safety.

Nothing is uploaded as a side effect. Even on the dev portal, an upload or publish happens only when the client asks for it. Building, previewing and QA all run locally.

Derive from the crawl, never from a template. Each site's rules come from that site's live pages. One site puts backgrounds on section wrappers; another puts the theme on each module panel and treats the section as a band behind it. Both are right for their own site.

Variant, never restyle. A module change adds a field whose default reproduces the current look, plus a modifier class and append-only CSS. Live pages keep rendering byte for byte. See Module conventions.

Iterate on the draft, not in HubSpot. Review rounds happen on local HTML drafts. The portal sees the page once it has been approved.

Write it down as it lands. Every HubSpot gotcha, upload and page id goes into the repo's CLAUDE.md the day it happens. That log is what lets you answer "what is on which portal" weeks later.

Where to start#

  • Working in Claude Code: install the plugin. Its skills cover each stage, and its guard hook enforces the account rules.

    /plugin install bb-hubspot --marketplace thomasjefferson/bb-hubspot

  • Setting up a new site: the New site checklist, then each page under The process in order.

  • Looking up a command: Tools. The site's constants: Site config.
  • Hitting a HubSpot error: HubSpot facts and Lessons and gotchas.