- ClayJS
- Build
- Editing a multi-page site
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.
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#
- Upload a public
site.json. Create one folder in Hyperclay, uploadsite.jsonfirst, and make it public:
{
"brandName": "Dr. Ines Okafor-Lindqvist",
"nav": [
{ "label": "Home", "href": "index.html" },
{ "label": "About", "href": "about.html" }
]
}
- Create
index.htmlwith thesiterule, matching markup, and ClayJS script. Map eachsitekey in<head>to an element in<body>, and load ClayJS at the end:
<!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>
-
Copy
index.htmltoabout.html. Replace<title>and<main>. Keep<script data-rules-name="api">and<header>identical so the selectors match on every page. -
Upload the pages, then media. Upload
index.htmlandabout.html, then any CSS, JS, SVG, or PDF files. Uploads need a paid plan. -
Open the page and edit. Open
index.html, turn on edit mode, and edit the brand name or nav. Saving updatessite.jsonandabout.html.
Things to watch for#
- Upload
site.jsonfirst and make it public. Upload your pages next, then media. - Use a paid plan to upload CSS, JS, SVG, or PDF files.
- Keep the
siterule and shared markup identical on every page. Missing elements or broken selectors refuse only that key asunreadable, 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, addedit-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
staleand 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.jsonunder 1 MB. Page edits cannot update a larger file (store-too-large). - Omit the
siterule on any page that should ignoresite.json.
Common tasks#
How do I add a page to the nav?#
- Duplicate a page in the Hyperclay dashboard and rename it, such as
teaching.html. - Update any active-link
<style>rule in<head>to nameteaching.html. - Add a nav item on any page pointing to
teaching.html(or add it insite.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:
<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:
<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:
<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:
<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:
<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:
<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:
<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 skipsdata-idon new rows, since shared projection copies row attributes onto siblings.edit-list="<noun>": adds a[sortable-handle]grip (drag or arrow keys viaclay.sortable.move), two-clickRemove?, andAdd <noun>from<template>(activecontenteditable="plaintext-only") oredit-from.edit-add="start",edit-min="<n>",edit-inline: insert at the top, block removal atn, or place pill controls above items (edit-kit.cssonly).edit-hide="<Name>",edit-upload: togglehidden, or addReplace image,Alt text, andUpload filecontrols (acceptfilter,clay.upload).data-id, keyboard: mintsdata-idoutside[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:
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 insite.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#
- In ClayJS and RichClay now: shared-edit tracking, the link popover,
editable="link-label", and relative URLs. - First (after two weeks of real editing):
edit-hideand two-click remove become a ClayJS plugin on Bevel, and the team reviews the attribute names then. - Second: list controls (
add-from, child<template>, shared selector,edit-add="start",edit-min) fold intocms, andsortablerebinds handles that appear after mount. - Third: upload becomes an attribute, with alt text inside
upload-ui.json Bevel. - Stays in the page: tag pills markup, filter bars, the Recent writing feed, and refusal notice wording.