Building the Brief & Ship Marketing Site

This is an internal case study, not a customer story. The subject is the site you are reading: an Astro repository built to explain Brief & Ship and to support a measured editorial program without adding a runtime application.

The useful result is not a screenshot. It is a set of decisions that remain inspectable in source and testable in the production build.

The brief

The site had to explain a product for people building professional websites with AI coding agents. It needed a clear commercial landing page, local brand assets, strong on-page SEO, and a path to publishing substantial technical content.

The content system introduced a second constraint: scale could not come from swapping variables into repeated templates. A new URL had to own a distinct problem and carry enough evidence, editorial depth, and internal context to deserve indexing.

The production target was global static delivery through Cloudflare. The site did not need authentication, a database, server rendering, or a client framework.

Architecture decisions

Astro runs with static output and directory-style routes. The production build produces HTML, CSS, local fonts, and optimized assets in dist. Cloudflare Workers Static Assets can serve that directory asset-first, which keeps normal page requests away from custom runtime logic.

The repository separates two kinds of content:

• a typed JSON entry for commercial home-page configuration;
• a Markdown collection for editorial pages, with frontmatter validated at build time.

One catch-all Astro route renders the editorial collection. It generates every public path during the build, creates canonical metadata, selects an article or hub presentation, resolves related entries, and produces JSON-LD from visible page data.

This avoids a directory full of nearly identical page components. It also avoids hiding critical metadata in an external CMS or build service.

Extending the existing visual system

The landing page already had a coherent language: Open Runde, a restrained Carbon and Linen palette, lavender action color, pill buttons, hairline borders, compact badges, and a 66-character reading measure.

The editorial implementation reused those decisions. It added composition, not another brand:

• a wider article header with the existing typeface and spacing rhythm;
• a sticky table of contents on large screens;
• a single readable content column;
• cards derived from the existing border, radius, and surface treatment;
• related-content and CTA sections that use the same visual grammar as the landing page.

Global landing selectors were narrowed so an article heading would not inherit hero proportions and every <details> element would not inherit FAQ styling. Mobile comparison tables retained real table semantics through horizontal scrolling instead of replacing headers with CSS-generated labels.

The content model

Every editorial entry names its content family, intent, voice, index status, primary query, related pages, author type, publication date, sources, and quality score.

The score has nine visible parts: search-intent fit, unique information, subject depth, evidence, editorial quality, commercial relevance, internal linking, technical SEO, and original examples. An indexable page must score at least 80, and the validator recalculates the total rather than trusting the number typed into frontmatter.

That gate is deliberately imperfect. It cannot decide whether an argument is insightful. It can stop a page from shipping with a score that does not add up, no parent hub, a duplicated primary query, or missing primary sources for technical claims.

Internal linking by construction

Each article declares a parent and a bounded list of related entries. The layout turns those references into breadcrumbs and related cards. Hub pages link to their spokes in the body, so category navigation remains useful even without the card rail.

The content checker resolves every referenced slug, validates Markdown and HTML links against generated routes, and rejects orphaned index pages. That makes internal linking part of the content contract rather than a cleanup exercise after publishing.

The first graph connects agent pages to comparisons, Astro guides, the AGENTS.md field guide, production problems, and this case study. It is intentionally small enough to review.

Choosing the initial publishing batch

The architecture can generate many routes. The initial release does not use that capacity as a target. It publishes a limited set of agent field guides, qualitative comparisons, audience workflows, technical guides, problem diagnoses, category hubs, and one internal example.

Several obvious page families were left empty. There are no competitor-alternative pages because the research and commercial comparison have not been completed. There are no fabricated vertical case studies. Labs lists planned methods but does not emit result pages for experiments that have not run.

This restraint is part of the implementation. The schema makes expansion predictable; the route inventory and quality gate make expansion reviewable.

Technical SEO controls

The base layout owns document language, viewport, local font preloads, favicon, canonical, robots, social metadata, and structured data. Editorial pages add publication dates and article-specific Open Graph values.

Structured data follows the visible content. Hubs use CollectionPage. Substantial editorial entries use Article. Every page adds a BreadcrumbList that matches the breadcrumbs shown above the title. Organization and website nodes share stable IDs. There are no fabricated people, ratings, reviews, awards, or offers.

The sitemap is generated from actual static routes. Drafts are not routed, so they do not enter the build or sitemap. The 404 page remains noindex and is excluded.

Performance choices

The editorial layer uses no hydrated framework components. Table-of-contents links, navigation disclosures, and article reading all use HTML and CSS. A small existing script records first-party CTA and FAQ interactions when an analytics layer is present; it does not load an analytics provider by itself.

Fonts and imagery are local. There are no third-party image hotlinks or immediate embeds. The production audit enforces budgets for CSS, JavaScript, fonts, raster images, and page HTML.

Static output does not guarantee a fast site on its own. A future editor could still add a large image, block rendering with a third-party script, or hydrate a component unnecessarily. The AI website performance guide describes those failure modes. The point of the repository checks is to make regressions visible before release.

Accessibility decisions

The implementation retains a skip link, visible focus treatment, semantic landmarks, a single H1, native navigation and disclosure elements, and reduced-motion handling. Article tables preserve headers and cells on small screens. Decorative brand marks have empty alternative text when the brand name already appears beside them.

Automated validation is not represented as complete accessibility certification. Keyboard behavior, zoom, screen-reader announcements, and contrast still need runtime review. A passing build proves the checks that ran, not every property a user can experience.

Deployment boundary

The repository includes a Wrangler configuration that points Static Assets to dist and selects the nearest 404.html for unmatched paths. Security and cache headers live in public/_headers, so they are copied into the generated output.

Deployment remains a separate authorized action. The local build can prove that files are ready; it cannot prove that a Git remote exists, Cloudflare credentials are correctly scoped, the custom domain is attached, or production returns the intended status code. Those items belong in release verification.

For the implementation path, see Astro on Cloudflare. For the agent operating layer, read AGENTS.md for website development.

What this example proves

It proves that this repository can build a static landing page and a typed editorial system with local assets, route generation, metadata, structured data, deterministic internal links, and automated production audits.

It does not prove that the commercial product guarantees rankings, conversion, accessibility compliance, or a perfect Lighthouse score. It does not prove one coding agent is better than another. Those claims need separate evidence, which is why unfinished experiments remain described in Labs rather than published as results.