How This Website Works

A quick look at how this site is built, hosted, and organized — and why it’s set up this way.

Why This Setup

The driving goal was the simplest possible way to turn basic Markdown files into cleanly styled web pages, managed entirely through Claude Code. I wanted to be able to say “create a new page about X” or “update the styling on Y” and have it just work — no CMS login, no drag-and-drop editor, no deploy scripts. Just Markdown files in a folder, a shared layout for consistent styling, and a push to main to publish.

Everything about the stack was chosen to minimize friction for that workflow: file-based routing so new pages are just new files, a single layout so styling is automatic, and static output so there’s nothing to manage on the server side.

Tech Stack

The site is built with Astro (v5), a static site generator that outputs plain HTML with zero JavaScript by default. Pages are either .astro components (for pages with custom layouts like the homepage) or plain Markdown files (for content-heavy pages like this one). Styling is done with scoped CSS and CSS custom properties in the layout and page components.

There’s one shared layout (Layout.astro) that wraps all Markdown content pages with consistent typography, navigation, and responsive styles. The homepage is its own standalone Astro component with a two-column grid layout.

Typography is Lora (serif, for headings) and Crimson Pro (serif, for the homepage body), with system fonts as the sans-serif fallback on content pages.

Hosting & Deployment

The site is hosted on Netlify with continuous deployment from a private GitHub repo. Every push to main triggers a build (astro build) and deploys the output from the dist/ directory. There’s no server — it’s fully static.

The netlify.toml config is minimal:

[build]
  command = "npm run build"
  publish = "dist"

Subdomains

notes.mattbrooks.xyz points to the /notes/ path of this same site using a Netlify rewrite rule. It’s not a separate site or repo — Netlify rewrites requests from the subdomain to the /notes/ path transparently (HTTP 200, not a redirect), so the subdomain URL is preserved in the browser.

Content Organization

All pages live in src/pages/ and use Astro’s file-based routing:

• Standalone pages — .astro files for the homepage, AI chatbot page, etc.
• Content pages — .md files with YAML frontmatter (title, layout) that get wrapped by Layout.astro
• Grouped content — subdirectories like consuming/ and notes/ with their own index pages that serve as directories for related content

Notes (like this one) use created and updated frontmatter fields for date tracking. The notes index page auto-discovers all Markdown files in the notes/ directory and lists them sorted by creation date.

What’s Not Here

No database, no CMS, no build pipeline beyond astro build, no client-side framework (React, Vue, etc.). The only JavaScript is a small scroll-tracking script on the homepage for mobile navigation highlighting. Everything else is static HTML and CSS.