How this site is built

Scope

This document describes how the site is built and published. It covers the stack, where content lives, and the steps to publish a change. It does not cover the visual design.

Stack

Layer	Choice	Why
Framework	Astro	Turns Markdown into static HTML with no client-side framework
Hosting	Cloudflare Workers	Static assets are served from Cloudflare’s network, with a Worker in front for anything dynamic
Source	Private GitHub repository	Every post is a file, so every change has a history

Static first

Every page is rendered to HTML at build time. The Worker only serves those files. Nothing on the page depends on JavaScript, apart from highlighting the current section in the contents list.

Content model

Posts are Markdown files in two folders. The folder decides the language and the site a post appears on.

src/content/posts/
  en/   English posts, published at /manual/ and /margins/
  ar/   Arabic posts, published at /ar/manual/ and /ar/margins/

Two kinds of writing

A post sets kind in its frontmatter:

manual posts are numbered documents with clause numbers, a revision history and a contents list.
margin posts are essays, set in a serif face without numbering.

Revisions

A document is revised rather than rewritten. Each revision is recorded in the frontmatter and shown in the revision history at the end of the document.

revisions:
  - date: 2026-11-02
    note: Added the rollback procedure

Publishing a change

Write or edit the Markdown file.
Preview it locally.
Commit, push and deploy.

npm run dev          # preview at http://localhost:4321
git add -A && git commit -m "Add a new document"
git push
npm run deploy       # build and upload to Cloudflare