Keep decisions explicit.
Brand, title, hero, sections, cards, CTA, language and metadata live in JSON rather than being scattered through markup.
CASE STUDY / CONTENT SYSTEMS
Brief to Page.
A validation-first static-page pipeline where content stays reviewable as structured data and the final HTML is deterministic, portable and safe to hand off.
THE PROBLEM
Fast page generation should not mean unreviewable output.
When a landing page is generated directly from a prompt, brand copy, links, metadata and layout decisions often collapse into one opaque artifact. That makes approvals, revisions and automation brittle. Brief to Page separates the content contract from rendering: a small JSON brief can be reviewed first, validated in CI, and rendered only after it passes defined boundaries.
Design constraint
The output must be a self-contained HTML file with no external runtime dependency, while unsafe URLs, malformed palette values and accidental source-file overwrite fail before delivery.
Brief, validate, render.
Fail before output.
--validate-only checks container shapes, palette values, CTA schemes, canonical URLs, OG image URLs and language tags without writing HTML.
Generate a portable artifact.
The result is one responsive HTML file with embedded CSS, escaped content and no JavaScript dependency.
Small tool, explicit trust model.
URL SAFETY
Constrained link schemes
CTA links allow only local paths, anchors, HTTP(S), mailto and tel. Canonical and OG image metadata require absolute HTTP(S) URLs.
OUTPUT PROTECTION
The source brief cannot be overwritten
The output path is resolved and compared against the input path before rendering, protecting the JSON source from accidental replacement.
INTERNATIONAL
Language is part of the contract
Pages can declare simple language tags such as ja, en and en-US without opening the HTML attribute to arbitrary injection.
SEO HANDOFF
Metadata is data, too
Title, description, optional canonical URL and optional Open Graph image are generated from the same reviewable brief.
REPEATABILITY
Validation can run in CI
A pull request can validate a campaign brief before a separate build step emits the final HTML artifact.
COMPATIBILITY
Tested across Python versions
The project runs regression tests across Python 3.10, 3.12 and 3.13 in GitHub Actions.
Review the brief before shipping the page.
$ python brief_to_page.py campaign/brief.json --validate-only
valid=1 sections=3 brand=Northstar Ops
$ python brief_to_page.py campaign/brief.json --output public/index.html
generated=public/index.html sections=3 brand=Northstar Ops
valid=1 sections=3 brand=Northstar Ops
$ python brief_to_page.py campaign/brief.json --output public/index.html
generated=public/index.html sections=3 brand=Northstar Ops
This pattern also works well with AI-assisted content generation: an AI can propose the brief, but the deterministic validator defines what is acceptable before HTML is emitted.
Why this matters beyond a demo.
Approval-friendly
Clients can review copy, CTA targets and page sections as structured content before layout generation.
Automation-friendly
The same brief format can be produced from forms, spreadsheets, internal tools or an AI workflow without coupling those systems to HTML internals.
Handoff-friendly
The delivered artifact is a single file, while the source brief remains readable and editable for the next iteration.
Need a repeatable content-to-page workflow?
I can adapt the same structured-brief pattern to landing pages, campaign variants, product pages or internal content pipelines.