Documentation site

The documentation in docs/ is served at docs.macmagic.app. It is the same tree GitHub shows and every other document links to; the site is a rendering of it, not a copy.

How it fits together

flowchart LR
    Docs["docs/**/*.md"] --> Shell["docs-site/ (Eleventy)"]
    Shell --> Out["_site/"]
    Out --> Worker["Cloudflare Worker macmagic-docs"]
    Worker --> Domain["docs.macmagic.app"]

docs-site/ holds the shell and no content: the layout, the stylesheet, the sidebar builder and the Eleventy config. Eleventy reads ../docs directly, so there is no sync step and no second copy of a document to keep in step.

What the shell derives

A docs generator normally asks its content for a title, an index file and links. These documents carry none of that, so the shell derives all three:

Titles come from each document's first # heading.
README.md is its folder's index, so docs/magical/README.md is served at /magical/.
Relative .md links are rewritten to the served URLs, so ../shared/widgets.md becomes /shared/widgets/. A link that leaves docs/, such as the pointer into specs/, is sent to GitHub rather than left to break.
The sidebar is built by walking the tree. docs-site/eleventy.config.mjs sets the section order; within a section the index leads and the rest follow alphabetically.

A fenced mermaid block renders as a diagram, and Pagefind indexes the built site for search.

Writing a document

Write it the way you always have. There is no front matter to add and no navigation to register; a new docs/<app>/<name>.md appears under its heading as its title. What belongs in a document is settled by ../README.md and the writing-docs skill, not by the site.

Running the site

Command	Action
`pnpm docs`	Serves the site locally with live reload.
`pnpm docs:build`	Builds `docs-site/_site` and its search index.
`pnpm docs:deploy`	Builds and deploys to Cloudflare.

The build runs eleventy and then pagefind, which indexes the output. Search is therefore a snapshot of the last build: the dev server rebuilds the HTML but not the index.

Deploying

.github/workflows/deploy-docs.yml deploys the Worker macmagic-docs from docs-site/wrangler.jsonc. It is assets-only, so a request serves a file rather than billing an invocation. The hostname is a Workers custom domain, which is why Cloudflare owns its DNS record and certificate. A pull request touching docs/ or docs-site/ uploads a version under a pr-<number> preview alias; a push to main deploys.

The theme

docs-site/assets/docs.css mirrors the tokens in website/src/assets/site.css. The two are separate copies, so a change to the palette belongs in both.