Site architecture

The idea

Write each page once, as data. Build every format from it at build time. People get HTML. Agents get Markdown and JSON-LD (structured data search engines read). Crawlers get the sitemap, feeds and llms.txt. Serve the result from memory, with its headers decided in advance. Run in the browser only what needs a browser.

1. Page data. Each page is one module or file with its path, title, description, date and content.
2. Build. One script and one stylesheet get hashed names. Every page is rendered with its CSS inline, plus metadata, JSON-LD, SRI and preloads.
3. Build checks. The build stops on any broken rule. It writes HTML, Markdown and JSON-LD for each page, a manifest, and compressed text files.
4. Server. Each page has one route and is rendered and compressed once, with its ETag and CSP hashes. Every response carries the security headers.
5. Machine files. Robots, the sitemap, feeds, llms.txt and the .well-known files are all built from the manifest.
6. Browser. Scripts only add behaviour, such as the theme, menus, widgets and the service worker.

Required

• Build on HTML that already works

  Required

  Ship working HTML first. Let JavaScript add behaviour to what is already there.

• Build repeated HTML from shared modules

  Required

  Build every repeated piece of HTML from one shared module, such as tables, code blocks, cards, breadcrumbs and calls to action. Make the build reject hand-written copies of the ones that break most easily.

• Give every module its own class names

  Required

  Give each module its own class names, so one module's styles can never reach into another.

Recommended

• Keep pages as data

  Recommended

  Write each page as plain values (path, title, description, date, HTML, Markdown), not as a template full of logic.

• Write each page once for every format

  Recommended

  Build every format (HTML, Markdown, JSON-LD, sitemap, feeds, llms.txt) from the same page data, so they cannot drift apart.

• Render at build time and serve from memory

  Recommended

  Do all templating at build time. Render each page once, compress it once, and keep the bytes, ETag and security policy in memory.

• Load one of each from your own site

  Recommended

  One HTML request, one inline stylesheet, one script bundle, one image per screen size, self-hosted fonts, and no third-party origins.

• Keep the previous build's assets

  Recommended

  After a deploy, keep the previous build's hashed files, so pages cached before the deploy still find their scripts.

• Audit every page in a browser before release

  Recommended

  Run an accessibility checker and Lighthouse in a real browser. Test light and dark mode, at phone and desktop width, and watch the console for policy errors.