Architecture

The site is a static Astro 7 build with TypeScript, styled with the YuTheme design language, deployed on Vercel. There is no server runtime.

Stack

• Astro 7 (static output)
• TypeScript
• pnpm (package manager, version pinned via packageManager)
• YuTheme tokens and editorial conventions (see design.md)
• Lucide icons inlined as raw SVG at build time, no icon runtime
• @astrojs/sitemap for sitemap generation
• Fonts: Geist Variable and Geist Mono Variable via Fontsource

No React, no Tailwind, no client-side framework. The only client JavaScript is a small vanilla script for the mobile menu, scroll reveal, and scrollspy.

Structure

docs/                      project documentation, served at /docs
public/
  favicon.svg              Ella monogram mark
  og.png                   social card, 1200x630
  robots.txt
src/
  components/
    Analytics.astro        Umami hook, env-gated, inert by default
    Footer.astro
    Header.astro           fixed header, scrollspy, mobile sheet
    Icon.astro             Lucide SVG map, typed icon names
    sections/
      Hero.astro           headline + terminal card
      About.astro
      WhatIDo.astro        card grid
      HowIWork.astro
      WhereILive.astro
      SelectedWork.astro   public work list
  content.config.ts        docs content collection (reads ./docs)
  data/site.ts             site constants: URLs, navigation
  layouts/BaseLayout.astro document shell, SEO, JSON-LD
  pages/
    index.astro            single-page home
    docs/index.astro       documentation index
    docs/[...slug].astro   individual documentation pages
  styles/global.css        YuTheme tokens, base styles, motion

Docs collection

Documentation pages read the docs/ folder of the repository root through an Astro content collection defined in src/content.config.ts:

• the loader is glob({ base: './docs', pattern: '**/*.md' });
• each entry needs frontmatter: title, description, order, updated;
• entries are rendered at /docs/<slug> with an index at /docs.

Because the collection reads the same folder that is versioned in the repository, the docs stay in sync: one source of truth, two views (site page and repo files).

Data flow

• Build time: Astro loads the docs collection and generates all static routes (/, /docs/, /docs/*).
• Content is prerendered; there is no server, no API, no runtime data.
• Analytics (Umami) is only injected when both PUBLIC_UMAMI_SRC and PUBLIC_UMAMI_WEBSITE_ID are set at build time.

Conventions

• Semantic HTML with a single h1 per page.
• Section headings ordered (h2 then h3), never skipped levels.
• External links open in a new tab with rel="noopener noreferrer".
• Reduced motion is respected everywhere: shimmer, reveals, and transitions are gated behind prefers-reduced-motion.