Repo template#
One repository per client site. Everything is plain Python 3 and the HubSpot CLI. The scripts need jinja2,
beautifulsoup4 (QA), Pillow (regression diffs) and python-docx (Word copies), and screenshots need a local
Chrome. bb-hubspot's templates/ folder holds the starting files.
Layout#
| Path | What it is | Made by |
|---|---|---|
hubspot-site.json |
Accounts, portal ids, File Manager URLs, theme, options | templates/hubspot-site.example.json, filled in (Site config) |
CLAUDE.md |
Working rules, HubSpot findings, the dated log | templates/CLAUDE.md, kept current by hand |
<theme>/ |
The theme, fetched from Design Manager | hs cms fetch |
reports/site-crawl.md / .json |
Section and module makeup of every live page | tools/crawl-site.py (site tool) |
DESIGN-RULES.md |
Archetypes, rhythm recipes, copy-shape → module tables | By hand, from the crawl |
MODULES.md / module-catalog.json |
Every module: fields, module_id, CSS hooks, live usage, annotations |
build-catalog.py |
catalog-annotations.json |
Hand-written notes per module | By hand (templates/catalog-annotations.json) |
STYLE-TAB.md |
The Style tab convention for rebuilt modules | templates/STYLE-TAB.md; checked by lint-style-tab.py |
drafts/previews/ |
One style-reference page per module | tools/build-previews.py (site tool) |
imports/<campaign>/<slug>.md |
Copy docs, one per page, no layout hints | tools/export-copydocs.py, or written new |
drafts/<slug>.html |
Page drafts with an @section annotation per section |
tools/build-page.py (site tool) |
pages.json |
Page registry: slug, template, copy doc, live source, dev and live ids | The build and publish scripts |
reports/qa/ |
Copy coverage, link and placeholder checks per draft | qa-draft.py |
assets/ |
Repo-local images, mirrored to the File Manager at the same paths | By hand |
tools/ |
The site tools, plus tools/fixtures/ (live header and footer markup) |
Written for this site |
backups/ |
Live module copies, page JSON, visual snapshots (git-ignored) | The live scripts |
.gitignore#
Copy templates/gitignore before the first commit. It covers the CLI config (hubspot.config.yml, .hscli/),
.env (the live service key), the crawl cache, backups/ and private/.
CLAUDE.md#
templates/CLAUDE.md is both the agent's working brief and the project's memory, in this order:
- Accounts & safety: the three accounts and the standing rules.
- Layout: what lives where in this repo.
- Dev portal state and Live state: one dated line per upload or publish, with ids.
- Composition rules: a short version of
DESIGN-RULES.md. - Module change discipline.
- HubSpot facts verified here: site-specific findings. Portable ones go back into these docs.
Log with dates and ids
Each log line has a date, what went where (module, page slug and id, File Manager path), and anything that is not done yet. "Nothing on live" is a useful sentence. Weeks later, this log is how you answer "is X on live?" without guessing.