# Editing a multi-page site

> Share a header, nav and footer across a folder of pages on Hyperclay, and edit them on any page: a quickstart, what to watch for, how-to recipes and technical notes.

Source: https://clayjs.com/docs/guide/multi-page-sites/

A ClayJS page stores its state in one HTML file. On Hyperclay, a public `site.json` turns its folder into a multi-page site. Each page saves itself, while `site.json` holds shared values for the header, nav, and footer.

## Quickstart

1. **Upload a public `site.json`.** Create one folder in Hyperclay, upload `site.json` first, and make it public:

```json
{
  "brandName": "Dr. Ines Okafor-Lindqvist",
  "nav": [
    { "label": "Home", "href": "index.html" },
    { "label": "About", "href": "about.html" }
  ]
}
```

2. **Create `index.html` with the `site` rule, matching markup, and ClayJS script.** Map each `site` key in `<head>` to an element in `<body>`, and load ClayJS at the end:

```html
<!DOCTYPE html>
<html lang="en" autosave>
<head>
  <meta charset="utf-8">
  <title>Home</title>
  <script type="application/json" data-rules-name="api" data-rules-version="1">
  {
    "site": {
      "brandName": ".site-brand-name",
      "nav": [".nav-list > li", { "label": "a", "href": "a@href" }]
    }
  }
  </script>
</head>
<body>
  <header>
    <a href="index.html">
      <span class="site-brand-name" editmode:contenteditable inert-contenteditable="plaintext-only">Dr. Ines Okafor-Lindqvist</span>
    </a>
    <nav aria-label="Primary navigation">
      <ul class="nav-list">
        <li><span editable="link-label"><a href="index.html">Home</a></span></li>
        <li><span editable="link-label"><a href="about.html">About</a></span></li>
      </ul>
    </nav>
  </header>

  <main>
    <h1 editmode:contenteditable inert-contenteditable="plaintext-only">Home</h1>
    <div editable><p>Welcome to the home page.</p></div>
  </main>

  <script src="https://clayjs.com/v1/clay.js?plugins=menu,indicator"></script>
</body>
</html>
```

3. **Copy `index.html` to `about.html`.** Replace `<title>` and `<main>`. Keep `<script data-rules-name="api">` and `<header>` identical so the selectors match on every page.

4. **Upload the pages, then media.** Upload `index.html` and `about.html`, then any CSS, JS, SVG, or PDF files. Uploads need a paid plan.

5. **Open the page and edit.** Open `index.html`, turn on edit mode, and edit the brand name or nav. Saving updates `site.json` and `about.html`.

## Things to watch for

- Upload `site.json` first and make it public. Upload your pages next, then media.
- Use a paid plan to upload CSS, JS, SVG, or PDF files.
- Keep the `site` rule and shared markup identical on every page. Missing elements or broken selectors refuse only that key as `unreadable`, while other keys save.
- Do not edit shared values in the Code tab. Change them on the page or in `site.json`.
- Never let a shared list become empty: Hyperclay refuses an emptied list as `empty-list`. With the academic site's edit kit, add `edit-min="1"` to every shared list so the last item cannot be removed.
- Only owning Hyperclay account members can save shared values. Share-link editors save the page, while shared edits get `not-allowed`.
- If another page just changed that shared value, Hyperclay refuses your edit as `stale` and shows the newer version. Edit it again.
- Keep the header, nav, and footer outside `<article data-blockeditor>`. Shared rules never write inside it.
- Keep `site.json` under 1 MB. Page edits cannot update a larger file (`store-too-large`).
- Omit the `site` rule on any page that should ignore `site.json`.

## Common tasks

### How do I add a page to the nav?

1. Duplicate a page in the Hyperclay dashboard and rename it, such as `teaching.html`.
2. Update any active-link `<style>` rule in `<head>` to name `teaching.html`.
3. Add a nav item on any page pointing to `teaching.html` (or add it in `site.json`). Every page's nav updates.

### How do I make a shared link?

Wrap each shared `<a>` tag in `<span editable="link-label">`. `site.json` stores only a plain-text `label` and an `href`:

```html
<ul class="nav-list" edit-list="page link" edit-min="1" edit-inline sortable>
  <template><li><span editable="link-label"><a href="index.html">New page</a></span></li></template>
  <li><span editable="link-label"><a href="index.html">Home</a></span></li>
  <li><span editable="link-label"><a href="cv.html">CV</a></span></li>
</ul>
```

`editable="link-label"` keeps one line of plain text inside one link and omits **Remove**, so every shared link keeps an address. The `edit-list`, `edit-min` and `edit-inline` attributes come from the academic site's edit kit (see below); without the kit, `link-label` works the same and the list simply has no add or remove controls.

### How do I link to a file in the folder?

Click the link, choose **Edit**, and type the relative file name, such as `cv.html`, `paper.pdf`, or `writing/twelve-hours.html`. Prefix bare slugs without extensions (`./about`) and dotted folders (`./v1.2/paper.pdf`) with `./` or `/` so ClayJS does not add `https://`.

### How do I let someone edit one page but not the shared values?

Send a share link for the page instead of adding the person to the owning Hyperclay account. They can edit the page and save page-own rules beside `site`, while Hyperclay refuses `site` edits as `not-allowed`:

```html
<script type="application/json" data-rules-name="api" data-rules-version="1">
{
  "essays": [".essay-list > .essay-item", {
    "title": ".essay-title",
    "url": ".essay-title a@href",
    "date": ".essay-date"
  }],
  "site": {
    "brandName": ".site-brand-name",
    "nav": [".nav-list > li", { "label": "a", "href": "a@href" }]
  }
}
</script>
```

### How do I show a message when a shared edit is refused?

Listen for `clay:site-data` on `document` and check `event.detail.refused`:

```html
<div id="site-notice" clay="editor-ui" role="status" hidden>
  <span id="site-notice-text"></span>
  <button type="button" onclick="this.parentElement.hidden = true">Dismiss</button>
</div>

<script>
const REFUSED = {
  "not-allowed": "Only the site's owner can change content that every page shares.",
  "empty-list": "A shared list needs at least one item.",
  unreadable: "A shared item is missing its text or its link.",
  stale: "Another page changed this shared content a moment ago. This page now shows that version; make your change again."
};

const notice = document.getElementById("site-notice");
const noticeText = document.getElementById("site-notice-text");

document.addEventListener("clay:site-data", (event) => {
  const { refused } = event.detail;
  notice.hidden = !refused.length;
  if (!refused.length) return;
  const reason = REFUSED[refused[0].code] || "The site's shared content could not be updated.";
  noticeText.textContent = `Your change to the shared header or footer was not saved. ${reason}`;
});
</script>
```

### How do I hide a shared block?

Map a `site` key to `@hidden` (`null` in `site.json` when visible) and add `edit-hide="<Name>"` with the academic site's edit kit:

```html
<script type="application/json" data-rules-name="api" data-rules-version="1">
{ "site": { "topBarHidden": ".masthead-top-bar@hidden" } }
</script>

<header class="site-header" edit-shared>
  <div class="masthead-top-bar" edit-hide="Top bar">
    <span class="masthead-affiliation" editmode:contenteditable inert-contenteditable="plaintext-only">University of Edinburgh</span>
  </div>
</header>
```

Hiding sets `hidden` on every page. In edit mode, `edit-kit.css` renders `Hidden: Top bar.` with a **Show** button, and clicking the placeholder also restores it.

### How do I keep a shared list from emptying?

With the academic site's edit kit, put `edit-min="1"` on every shared list alongside `edit-list`:

```html
<ul class="footer-lines" edit-list="line" edit-min="1" sortable>
  <template><li><span class="footer-line" editmode:contenteditable contenteditable="plaintext-only">New line</span></li></template>
  <li><span class="footer-line" editmode:contenteditable inert-contenteditable="plaintext-only">University of Edinburgh</span></li>
</ul>
```

`edit-min="1"` disables removal on the last item. Hyperclay also refuses an empty list as `empty-list` because shared projection clones a sibling row.

## Using the academic site's edit kit

The academic site (`starter-templates/sites/academic-site/`) loads `edit-kit.css` and `edit-kit.js` with `editmode:resource` so view mode fetches neither:

```html
<link editmode:resource type="inert/text/css" rel="stylesheet" href="edit-kit.css">
<script editmode:resource type="inert/text/javascript" src="edit-kit.js"></script>
<script src="https://clayjs.com/v1/clay.js?plugins=menu,indicator,sortable,undo,upload"></script>
```

In edit mode, the kit adds `clay="editor-ui"` controls and records edits with `clay.undo.commit`:

```html
<a href="cv-okafor-lindqvist.pdf" download edit-upload=".pdf">Download CV (PDF)</a>

<section edit-hide="Appointments">
  <template id="bp-cv-entry"><div class="cv-entry"><div class="cv-role" editmode:contenteditable contenteditable="plaintext-only">Role</div></div></template>
  <div class="cv-entries" edit-list="entry" edit-from="#bp-cv-entry" sortable>
    <div class="cv-entry" data-id="cv-appt-1">
      <div class="cv-role" editmode:contenteditable inert-contenteditable="plaintext-only">Associate Professor</div>
    </div>
  </div>
</section>
```

- `edit-shared`: outlines shared regions on hover and skips `data-id` on new rows, since shared projection copies row attributes onto siblings.
- `edit-list="<noun>"`: adds a `[sortable-handle]` grip (drag or arrow keys via `clay.sortable.move`), two-click `Remove?`, and `Add <noun>` from `<template>` (active `contenteditable="plaintext-only"`) or `edit-from`.
- `edit-add="start"`, `edit-min="<n>"`, `edit-inline`: insert at the top, block removal at `n`, or place pill controls above items (`edit-kit.css` only).
- `edit-hide="<Name>"`, `edit-upload`: toggle `hidden`, or add `Replace image`, `Alt text`, and `Upload file` controls (`accept` filter, `clay.upload`).
- `data-id`, keyboard: mints `data-id` outside `[edit-shared]` and shows an **Options** button on focused `[edit-upload]` and visible `[edit-hide]` elements.

## Technical notes

### What a save sends

ClayJS loads `core/site-edits.js` only in edit mode, outside draft mode, when `api` rules declare a top-level `site` key. Each save sends `Site-Data` with changed top-level `site` keys in rule order, URL-encoded and comma-separated:

```http
Site-Data: keys=topBarHidden,nav
```

When you changed none, ClayJS sends `Site-Data: keys=`.

### How ClayJS decides what changed

ClayJS compares HTML snapshots through the `site` rule and never reads the live DOM. Boot captures `getLastSavedContents` as the baseline before editing starts. Accepted saves here and clean live-sync frames advance it, while dirty morphs do not. Edits typed during load differ from the baseline, so ClayJS declares them. Live-sync updates match the baseline, so ClayJS skips them.

### What the host does with it

The host writes declared keys to `site.json` first. Object rules merge key by key, and list rules replace the whole list. The host then projects `site.json`'s shared values into the page (never inside `<article data-blockeditor>`) so a stale tab cannot restore old shared values. When `site.json` changes, the host copies its shared values into every page in the folder, and subfolders without their own `site.json`, that declares `site`.

### The host's answer and refresh behavior

When a save writes, refuses, or refreshes shared values, the host returns `siteData` (also on `clay.save()`), omitting it when all three fields are empty:

- `written`: keys stored in `site.json`.
- `refused`: `{ key, code }` entries (`not-allowed`, `empty-list`, `unreadable`, `stale`, `unknown-key`, `store-too-large`, `store-unreadable`).
- `current`: newer shared values this tab lacked.

ClayJS applies `current` to untouched keys inside `Mutation.pause()` to stay out of undo history, dispatches `clay:external-write` on rewritten `[editable]` fields to reset RichClay's undo baseline, and triggers an automatic save. Refused keys keep your edit and stay declared, except `stale`, which takes `current`. When `siteData` is present, ClayJS dispatches `clay:site-data` on `document` with `detail: { written, refused, applied }`.

### Link popover details and URL rules

With the caret in a link, RichClay shows the shortened URL (no `Open` label), **Edit**, and **Remove**. `Escape` hides the bar until the caret leaves and returns. Clicking opens safe URLs (`http:`, `https:`, `mailto:`, `tel:`, or scheme-less paths) in a new tab or app, while unsafe URLs (`javascript:`, `data:`) omit `href` and render plain text.

`editable="link-label"` offers only **Link**, **Undo**, and **Redo**, ignores `Cmd+B`, `Cmd+I`, `Cmd+U`, and `format*` inputs, pastes plain text, keeps `href` when typing after or over the label, and wraps the whole label. `normalizeUrl` keeps file names with a known extension (document, image, archive), paths with a folder whose first part has no dot (`writing/about`), and links starting with `#`, `?`, `/`, `./`, or `../`. A bare word such as `about` gets `https://`. Bare hosts (`example.org`) get `https://`, and bare emails get `mailto:`.

### Edit-kit roadmap

1. **In ClayJS and RichClay now:** shared-edit tracking, the link popover, `editable="link-label"`, and relative URLs.
2. **First (after two weeks of real editing):** `edit-hide` and two-click remove become a ClayJS plugin on Bevel, and the team reviews the attribute names then.
3. **Second:** list controls (`add-from`, child `<template>`, shared selector, `edit-add="start"`, `edit-min`) fold into `cms`, and `sortable` rebinds handles that appear after mount.
4. **Third:** upload becomes an attribute, with alt text inside `upload-ui.js` on Bevel.
5. **Stays in the page:** tag pills markup, filter bars, the Recent writing feed, and refusal notice wording.
