Sites

Sites

Status: agreed, not built. Today one VitePress site in web/ serves everything at enumeratio.dev. This page is the plan for two sites, one per name (Names), and the promise the catalogue's URLs make. How the current site deploys is on CI and Deployment.

1. Two sites

	enumeratio.dev	notatio.app
What it is	The catalogue: mathematical objects, to explore and to cite	notatio: how to write and show an expression, and the notebook
Reference	/reference/symbol/<Head> for every mathematical head, compute-engine's own included; /reference/statistic/…, /reference/map/…; the collection, domain, statistic and map indexes	/reference/symbol/<Head> for the presentation heads; /reference/component/<Name>; /reference/formats/…
Docs	/docs/<library>/… for the enumeratio libraries and the catalogue's machinery; /guide/	/docs/<package>/… for components, frontend, boxes, formats, cli, raster, wolfram
Live pages	/explore/…, /bench/	/notebook/, /worksheet/, /playground/…
Data	/schema/*.schema.json	none

The catalogue is built with notatio: a symbol page's live cells, plots and tables are notatio components. The dependency runs one way. The notatio site loads the enumeratio libraries only as content for its notebook and examples.

Where a head's page goes. By its package. A head from a presentation-layer package (enumeratio.layer in package.json) or from boxes is notatio's; every other head is the catalogue's. boxes is named because it sits in the base layer: structures builds on it. A field in package.json should state the site, so the rule reads one value and has no exception list.

Each site links the other absolutely. A package's docs link the catalogue as https://enumeratio.dev/… and notatio as https://notatio.app/…, so a page reads the same on GitHub and on either site.

2. The promise

A URL published on enumeratio.dev answers for good: with the page, or with a redirect to where the object now lives. This covers:

• /reference/symbol/<Head>, and its #example/<id> anchors;
• /reference/statistic/<carrier>/<name> and /reference/map/<carrier>/<name>;
• /schema/*.schema.json, which the record schemas name as their $id;
• any address later given to a collection, an element or a structure (§7).

What the promise allows: a head is renamed and its old page redirects; a statistic's page folds into its collection's and redirects to the field there. What it forbids: a published URL that returns nothing.

The ledger. A committed, append-only list of every URL pattern and every head name ever published. A test over the built site and its redirect rules fails when a ledger entry neither resolves nor redirects. Renaming or retiring a head therefore needs its redirect in the same change. Example ids are already stable by rule (Examples as Data).

notatio's URLs make no such promise. Whether notatio.app gets a ledger of its own is not decided.

3. Redirects

Today's redirects are HTML stubs written at build (a meta refresh and a canonical link). They become real redirects in a Cloudflare Pages _redirects file, generated at build from the same tables:

• a family that moves hosts is one rule with a splat: /reference/component/* to https://notatio.app/reference/component/:splat;
• a presentation head's symbol page is one rule per head, generated from the manifest;
• the existing moves, renames and retired stubs keep their rules.

Cloudflare limits how many rules a project may have, so whole families use a splat and only per-head moves take a rule each. A browser carries the #fragment across a redirect, so example anchors survive.

4. The build

web/ becomes two VitePress apps over a shared theme:

• a shared, private theme package: the markdown plugins, the reference page, the record and docs loaders, the kernel worker setup;
• the enumeratio app: the catalogue's routes over the records, filtered by the rule in §1;
• the notatio app: the component, format and presentation-head routes, the notebook and the worksheet.

Both read records through @notatio/reference/node and package docs through the same loader, each keeping the packages that are its own. Each app builds only what it serves, so a change to a notebook page does not rebuild the catalogue.

Places that hold the site's address today and need a second one: the docs loader's siteOrigin, the manifest's symbol URL (describe), the review tooling's production host, and the links in package READMEs.

5. Deployment

• A second Cloudflare Pages project, notatio, beside enumeratio: a classic Pages project like it, production branch main. The project exists and has no deployment until the notatio site builds. Its custom domain is notatio.app, a zone of its own on Cloudflare.
• Previews: <sha7>.enumeratio.pages.dev and <sha7>.notatio.pages.dev. The pull request's sticky preview comment carries both.
• Production: each project deploys its own build on merge to main.
• Preview clean-up runs over both projects.
• Creating a project and attaching a domain are done once, by hand, with the maintainer's Cloudflare login; CI only deploys to a project that exists, with the token and account id it already holds. wrangler pages project create makes a Workers static-assets project unless given --force, which makes a classic Pages project. wrangler has no command for a Pages custom domain: that is set in the dashboard, under the project's custom domains.

6. CI and the cache

• tools/ci/affected.ts selects each site on its own: a site is affected when its app, the shared theme, or a package it depends on changes. A record change selects the site that serves that record.
• tools/ci/dist-cache.ts leaves both apps out of the library build, as it leaves web out today.
• The required check keeps its name, check + site build, and waits on both builds.
• The nightly tarball check builds both apps from the packed tarballs.
• The hydration and story checks run against the app that has those pages.

7. Order of work

Each step leaves every published URL working.

1. Ledger and test on the site as it is. Nothing moves.
2. _redirects replaces the HTML stubs, with the same sources and targets.
3. Shared theme split out of web/, still one site.
4. The notatio app builds and deploys to notatio.app, serving its pages. The same pages stay on enumeratio.dev, with their canonical link pointing at the new host.
5. The flip. On enumeratio.dev the moved families become redirects; navigation, absolute links and the manifest's URLs follow. enumeratio.dev's title becomes "enumeratio".
6. Trim. The enumeratio app drops the routes it no longer serves.

Open

• Addresses for objects. There is no URL today for a collection instance, one element of it, or one specific structure. The address is the expression that names it; its URL form is not designed. It is additive to the routes above and comes under the promise when published.
• Saved notebooks by link. A notebook reached by a link is a published URL on the notatio side; what it promises is decided with that design.
• /playground/inspirations/ is placed on the notatio site as pages about interfaces. Some of them are about mathematics and may sit better in the catalogue's guides.