# Multi-page sites

> Make a folder a site: its pages share values such as a name and a navigation bar from one site.json file, answer at clean addresses, and can share one domain.

Source: https://hyperclay.com/docs/multi-page-sites/

A site is a folder of pages that share some values, such as the site's name and its navigation links. You keep those values once, in a file named `site.json`, and Hyperclay writes them into every page. Each page stays a complete HTML file that works on its own.

## What a site is

A folder is a site when it directly holds a public file named `site.json`. There is no other switch. If the file is not a valid JSON object, the folder is still a site, but no values reach the pages until you fix it.

- A site covers its subfolders too. If a subfolder has its own `site.json`, that file applies to the pages under it: the nearest `site.json` wins.
- `site.json` is a reserved file name.
- `site.json` is public. Anyone can read it by its URL.

> [!WARNING]
> Never put a secret in `site.json`. Anyone who knows the folder's address can read the whole file.

## Make a folder a site

1. In the dashboard, open the folder's menu and choose **Mark as site**.
2. Hyperclay creates `site.json` holding `{}` and opens it in the **Code** tab.
3. Add your shared values and save.

If the folder already has a `site.json`, **Mark as site** refuses and leaves the file as it is. A folder that is already a site shows **Edit site data** in its menu instead, which opens `site.json` in the **Code** tab.

An agent with an Edit key can also publish a local folder as a site with [clay-agent](https://hyperclay.com/docs/agents/#publishing-a-folder): `npx -y @panphora/clay-agent publish ./maya demos/maya`.

## Show shared values on a page

Each page says where each shared value goes. It does this in its [`api` rules tag](https://hyperclay.com/docs/page-data/), under a reserved key named `site`. The rules inside `site` use the same [selector grammar](https://clayjs.com/docs/plugins/data/#rules-reference) as any other rule, and they sit beside the page's other `api` rules.

Here the folder `ada` has this `site.json`:

```json
{
  "name": "Ada Lovelace",
  "nav": [
    { "label": "Home", "href": "/ada/" },
    { "label": "About", "href": "/ada/about" }
  ]
}
```

And `ada/about.html` says where those values go:

```html
<head>
  <title class="site-name">Ada Lovelace</title>
  <script type="application/json" data-rules-name="api" data-rules-version="1">
  {
    "site": {
      "name": ".site-name[*]",
      "nav": ["nav a", { "label": ".", "href": "@href" }]
    }
  }
  </script>
</head>
<body>
  <header><span class="site-name">Ada Lovelace</span></header>
  <nav>
    <a href="/ada/">Home</a>
    <a href="/ada/about">About</a>
  </nav>
  <footer><span class="site-name">Ada Lovelace</span></footer>
</body>
```

Change `"name"` in `site.json` and the title, header and footer change on every page that has this rule. Add a third item to `"nav"` and every page gets a third link, copied from its first link. A page takes only the values its `site` rules name, so a page with no `nav` rule ignores `nav`.

### Write every match with `[*]`

A rule for a single value, such as `".site-name"`, writes only the first element it matches. Add `[*]` after the selector, as in `".site-name[*]"`, to write every match: the header, the footer and the title. When you read data, `.site-name[*]` returns the first match.

`[*]` works on hyperclay.com, in ClayJS and in Hyperclay Local. HTML Clay adds it in its next release.

### Text and attributes only

Shared values are only ever text and attribute values. They never write scripts, `<meta>` or `<link>` tags, or raw HTML.

## What happens when site.json changes

When `site.json` changes, Hyperclay writes the new values into every page of the site, through each page's own rules, and saves each page that changed.

- Each changed page gets one new version in its [version history](https://hyperclay.com/docs/version-history/), marked as a site data update and credited to the person who changed `site.json`.
- A page that already holds the new values is not saved and gets no new version.
- A page open in edit mode in a browser tab updates while you watch.
- The values are plain markup in each HTML file, so the pages work offline and after you download them.

Values flow one way, from `site.json` to the pages. A page save never changes `site.json`. Every save writes the current `site.json` values into the page, so a tab that loaded old values cannot put them back when it saves later. Restoring an old version of a page also keeps today's shared values. To change a shared value, change it in `site.json`, not on a page.

## Ways to change site.json

1. **The Code tab.** Choose **Edit site data** in the folder's menu, change the JSON and save. This needs the same permission as any other edit in the [Code tab](https://hyperclay.com/docs/code-editor/).
2. **The site data API.** Read and write `site.json` over HTTP. See [Change site data from a script](#change-site-data-from-a-script).
3. **Hyperclay Local or the sync API.** In a synced folder, upload a changed `site.json`. The pages update, and the updated pages sync back to you. A page uploaded through sync is stored with the current shared values, so it can come back slightly different from what you sent. See [Sync API](https://hyperclay.com/docs/sync-api/).
4. **Agents.** An agent key reads and writes `site.json` through any page in the site, inside the folders the key can reach, and an Edit key can create or replace `site.json` when [publishing a folder](https://hyperclay.com/docs/agents/#publishing-a-folder). See [site data for agents](https://hyperclay.com/docs/agents/#site-data).

### Change site data from a script

`site.json` has an address under `/_/api` on your account address. On a domain attached to the site folder, the address is `/_/api/site.json`.

```
https://<username>.hyperclay.com/_/api/ada/site.json
```

- `GET` returns the object with an `ETag`. Anyone can read it, from any origin.
- `POST` merges top-level keys, so send only what changes. `PUT` replaces the whole object.
- `""` and `[]` are real values: they clear what the pages show. A key that is missing from `site.json` leaves the pages as they are.
- `If-Match` is checked when you send it. You do not have to send it.
- You, your team's editors and your [sync key](https://hyperclay.com/docs/sync-api/) can write. A share link for one page cannot, so sharing a page never hands over the site. Send the body as `application/json`.

```bash
curl -X POST https://<username>.hyperclay.com/_/api/ada/site.json \
  -H "X-API-Key: $HYPERCLAY_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name": "Ada King"}'
```

```json
{ "etag": "...", "changed": true,
  "pages": { "total": 5, "updated": 5, "unchanged": 0, "failed": [], "pending": false } }
```

If the pages take longer than 8 seconds, `pages` is `{ "pending": true }` and the work finishes in the background. Sending the same values again answers `"changed": false` and does nothing. The status codes are listed in the [platform reference](https://hyperclay.com/docs/platform-reference/#site-data).

## When a page cannot be updated

Hyperclay writes each page on its own and never rolls the others back. If one page cannot take a value, the other pages still update. The usual cause is a rule that matches nothing, for example a page whose `nav` rule finds no `<a>` inside a `<nav>`.

With `site.json` open in the **Code** tab, a line under the editor shows how many pages are up to date. It names each page that was not updated and the reason, and offers **Retry**. Fix the page's markup or its rules, then click **Retry**. If `site.json` is not valid JSON, the line says so, and no page is updated until you fix it.

A script sees the same list in `pages.failed` in the API answer.

## Add, move and remove pages

- A new page in the site, or a page moved into it, takes the site's values.
- A page moved out of the site keeps its last values and stops updating.
- Moving `site.json` to the [trash](https://hyperclay.com/docs/trash/), or deleting it, stops updates and leaves every page exactly as it is. Restoring `site.json` from the trash makes the folder a site again.
- Renaming another file to `site.json`, or moving a `site.json` into a folder, makes that folder a site.

## Clean addresses

Inside a site, pages answer at addresses without `.html`. `ada/about.html` answers at `/ada/about`. Hyperclay looks for a path in this order:

1. The exact file.
2. `<path>.html`
3. `<path>.htmlclay`
4. `<path>/index.html`
5. An upload, such as a PDF.

Inside a site, a path that names nothing answers 404.

- Opening `/ada/about.html` redirects to `/ada/about`. The redirect is temporary (302), so if you delete `site.json`, the `.html` addresses come back.
- An index page opened without its trailing slash redirects to the slash form, so `/ada/docs` goes to `/ada/docs/` and its relative links work.
- Saves and API calls never redirect.
- Relative links such as `about.html` keep working everywhere, offline too.
- A page whose clean address would clash with a word Hyperclay reserves for its own actions, such as `edit`, keeps its `.html` address.

Outside a site, addresses do not change.

## Put a site on its own domain

A [Hyperclay subdomain](https://hyperclay.com/docs/addresses/) or a [custom domain](https://hyperclay.com/docs/custom-domains/) can point at a site folder, as well as at a single document. Open the folder's menu and choose **Hyperclay subdomain** or **Custom domains**. An agent with an Edit key can claim the subdomain for you with clay-agent: `npx -y @panphora/clay-agent subdomain --site demos/maya maya`.

A domain on a site folder serves the whole folder:

- `index.html` at `/`
- the other pages at their clean addresses
- uploads at their paths inside the folder
- 404 for a path that names nothing

Only a folder that is a site can have a domain. Wildcard domains cannot point at a folder. If you rename or move the folder, its domain keeps working.
