# Sites
Status: **agreed, partly built**: the ledger and the `_redirects` file exist (§7 steps 1 and 2); the second site does not. 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|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/
` for every mathematical head, compute-engine's own included; `/reference/statistic/…`, `/reference/map/…`; the collection, domain, statistic and map indexes | `/reference/symbol/` for the presentation heads; `/reference/component/`; `/reference/formats/…` |
| Docs | `/docs//…` for the enumeratio libraries and the catalogue's machinery; `/guide/` | `/docs//…` 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 package's site follows its npm scope, and the `package.json` field that once stated it is
gone. Every package is `@notatio/*` today; a data package under `@enumeratio/*` would belong
to enumeratio.dev.
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/`, and its `#example/` anchors;
- `/reference/statistic//` and `/reference/map//`;
- `/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|Examples-as-Data]]).
notatio's URLs make no such promise. Whether notatio.app gets a ledger of its own is not
decided.
## 3. Redirects
Redirects are 301 rules in a Cloudflare Pages `_redirects` file, generated at build from the
same tables (`web/.vitepress/redirects.ts`):
- 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: `.enumeratio.pages.dev` and `.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. Built: `web/ledger.tsv` and its test.
2. **`_redirects`** replaces the HTML stubs, with the same sources and targets. Built.
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.