Hyperclay
  1. Hyperclay
  2. Docs
  3. Publishing
  4. Multi-page sites

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.

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.

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: 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, under a reserved key named site. The rules inside site use the same selector grammar 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, 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.
  2. The site data API. Read and write site.json over HTTP. See 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.
  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. See site data for agents.

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.

plaintext
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 can write. A share link for one page cannot, so sharing a page never hands over the site. Send the body as application/json.
Shell
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.

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, 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 or a custom domain 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.