Refactor site generation into a modular content pipeline

README.md

@@ -21,5 +21,29 @@ bun install
 bun run dev
 ```
 
-Run `bun run check` to validate generated pages and `bun run build` to create
-the production site in `dist/`.
+Run `bun run test` for focused content and output tests, `bun run check` to
+validate generated pages, and `bun run build` to create the production site in
+`dist/`.
+
+### Project layout
+
+- `site.config.js` defines the site URL, content directories, standalone pages,
+  and files watched by the development server.
+- `content.js` discovers Markdown pages and handles local drafts. A file named
+  `.example.md` in `notes/` or `posts/` is a local draft; `bun run dev` includes
+  drafts, while builds exclude them.
+- `generator.js` renders static pages. `feed.js` renders the RSS feed and sitemap.
+  `output.js` stages the generated site before replacing `.generated/`, so a
+  failed generation leaves the previous output available.
+- `src/` contains browser behavior, styles, and bundled fonts.
+- `vite.config.js` builds the generated pages and regenerates them after content
+  changes during development.
+- `check.js` validates the generated output before each production build.
+
+Edit content in `notes/` and `posts/`. Keep generated files in `.generated/`
+and `dist/` out of version control.
+
+`mirror/` contains local copies of API references (`docs.gl`, Microsoft SDK
+API, and Win32). It is about 906 MB, is not used by the generator or build,
+and is ignored by Git. Keep it locally for reference or move it outside the
+project when no longer needed.