Skip to main content
Blueprint

Built with Cosmo

Behind-the-scenes on how this site was built on top of Cosmo.

Last updated

This site runs on the Cosmo template. The original purpose was to find any rough edges that needed to be smoothed out for the developer experience. If you’re adapting Cosmo for a marketing or docs site, this is a real world look into how it works.

You can find the source code here.

When Cosmo is the right pick

Cosmo was made for a wide range of static sites: portfolios, blogs, etc. If you need versioned docs, deep nav, built-in search, or i18n on day one, Starlight gives you all of that out of the box. Cosmo trades those features for an agnostic codebase with minimal opinionated code.

What we removed

  • There’s no blog on this site, so we pulled src/content/blog/, dropped the blog entry from src/content.config.ts, and removed the matching routes (src/pages/blog/, src/pages/tags/).
  • The blog-specific layouts and partials that came with it.
  • The example posts the template ships with.

What we kept

  • The Hero, Marquee, Features, and Charts sections under src/components/sections/ are template-derived. All we did was style it and add internal links.
  • Another style refresh on the Navbar and Footer with the links now pointing at our docs and the GitHub repo.
  • The theme system’s design tokens in src/styles/global.css, plus the dark/light mode toggle and the motion preference toggle.
  • The astro-seo wrapper at src/components/SEO.astro, with siteName and titleDefault swapped over.
  • Astro fonts via the astro:assets Font component, which are wired up in BaseLayout.
  • The reusable Callout component handles note, tip, warning, and danger.

What we added

A docs content collection

Defined in src/content.config.ts with a tight Zod schema (title, description, order, updatedDate, draft).

Two routes render it:

  • src/pages/docs/index.astro — a themed card grid, sorted by order.
  • src/pages/docs/\[slug\].astro — the detail page, with a table of contents, prev/next, an “edit on GitHub” link, and JSON-LD.

Per-doc themed backgrounds

A small lookup at src/lib/doc-themes.ts maps each doc slug to a visual theme: Solar System, Pulsar, and so on. New docs without a registered theme fall back to the “Deep Space” nebula.

Blueprint + roadmap + privacy + a custom 404

The page you’re reading is itself an addition. src/pages/blueprint.mdx and src/pages/roadmap.mdx each get their own layout, EventHorizonLayout.astro and PortholeLayout.astro, so they can have a distinct visual identity from the rest of the site without bleeding into BaseLayout.

Additionally, there are two more top-level Astro pages at src/pages/privacy.astro and src/pages/404.astro.

A weighted sitemap

@astrojs/sitemap is wired up in astro.config.mjs with custom changefreq and priority values. The 404 is excluded, and /privacy is deprioritized.

JSON-LD schema

Two flavors:

  • WebSite + Organization on the homepage.
  • TechArticle + BreadcrumbList on each doc detail page.

Both are emitted as inline <script type="application/ld+json"> in BaseLayout.astro and in [slug].astro respectively.

Dismissible popovers

Two small persistent UI bits live in BaseLayout.astro: NoCookieBanner.astro (a one-time “cookieless analytics” disclosure, dismissal stored in localStorage) and KoFiPopover.astro (a Ko-fi support nudge, dismissal stored in sessionStorage so it returns once per visit). Neither sends any data anywhere and hide themselves once dismissed.

Cookieless analytics

Cloudflare Web Analytics has no consent banner because there are no cookies nor session replay. DNS lives at Namecheap rather than going through Cloudflare’s proxy, so the beacon is injected by hand in BaseLayout.astro instead of relying on auto-injection. The CSP allows static.cloudflareinsights.com in script-src and cloudflareinsights.com in connect-src.

Security headers

Set in public/\_headers: CSP, HSTS, X-Content-Type-Options, Referrer-Policy, and Permissions-Policy. The CSP allows 'unsafe-inline' in script-src because Astro 6 inlines hoisted <script> tags by default. The XSS surface here is essentially zero since there is no user-rendered HTML.

Theme + motion bootstrap, lifted into public/theme.js

A blocking script that runs before paint to set the initial theme and motion preference, so you don’t get a flash of unstyled content. It lives outside the bundler so the document <head> can pull it in synchronously.

Cached GitHub stars badge

The Hero shows a star count for the upstream Cosmo repo. Instead of pulling shields.io at runtime (which would mean a third-party request on every page view, plus an extra img-src entry in the CSP), the count is cached in src/data/stars.json and refreshed by a daily GitHub Action (.github/workflows/update-stars.yml) that hits the GitHub API and commits the updated JSON. The Hero reads the file at build time and bakes the number into the static output.

In-site search is wired up via Pagefind through the astro-pagefind integration. The index is generated at build, lives entirely in dist/, and is loaded lazily by SearchPanel.astro only when the user opens the search overlay.

Curtain page transition

Page navigations are intercepted in BaseLayout.astro: a click on an internal link draws a three-layer curtain over the page, then performs a full document load. The new page boots with the curtain already covering it (signalled via sessionStorage) and animates it open after the document is ready. All the animation work lives in .page-curtain* rules in src/styles/global.css, and the entire effect is gated behind prefers-reduced-motion.

Build-time OG images

Open Graph images are generated at build by astro-og-canvas via the dynamic route at src/pages/open-graph/[...route].ts. The route enumerates the docs content collection and a small static map (home, blueprint, roadmap, privacy) and emits a themed PNG per page. SEO.astro points each page’s og:image at the matching route.

Google Search Console verification

Added as a <meta name="google-site-verification"> tag in BaseLayout.astro. We went with the HTML tag method instead of DNS so verification stays next to the site config.

Recipes we used

This site is mostly Cosmo in its plainest form. The few “recipes” we leaned on are documented separately:

Cookieless analytics and no session replay. We respect your personal space.