Hyperclay
  1. Hyperclay
  2. Guide
  3. Making malleable documents

Making malleable documents

Hyperclay runs malleable documents built with ClayJS. What ClayJS does, where to learn it, and how to bring your own file into Hyperclay.

You make malleable documents with ClayJS, and the ClayJS docs are the place to learn it. This site covers the Hyperclay hosted platform, not how to build documents from scratch. When you want to build your own malleable document, go to the ClayJS docs.

What ClayJS does#

ClayJS is the free, open-source browser library that turns one HTML file into a malleable document. Every malleable document is built with it.

  • One script tag: Add a single script tag to an HTML page with no build step.
  • Edits in place and saves to its host: Make elements editable, persist form controls and DOM state, strip temporary editing controls on save, and write the updated HTML back to its host.
  • Live sync: Merge changes in real time across open browser tabs and people.
  • Plugins: Load plugins such as the schema-driven CMS, rich-text editing with richclay, sortable lists, undo, uploads, and AI editing.
  • Works anywhere: Run the same file on Hyperclay, HTML Clay, Hyperclay Local, or your own server.

Learn ClayJS#

Import an HTML file#

If you already wrote a malleable document on your computer, or if you have static .html, .htm, or .htmlclay pages (or a .zip archive of pages such as a Notion or Google Docs export), you can import them into your workspace as documents:

  1. Open the folder in your workspace where you want the document to live.
  2. Click New and choose Import files….
  3. In the Import files dialog, click Choose files… and select one or more .html, .htm, .htmlclay, or .zip files.

Each imported HTML page becomes a document in the current folder. File names are lowercased and normalized to end in .html or .htmlclay, with -2, -3, and so on added if the name is already taken in that folder. Each page can be up to 5 MB. Any non-HTML files inside a .zip archive are added to your uploads. See Import and export for full details.

At the bottom of the Start a new document gallery, the Have a file already? strip (Choose a file) opens the Upload files dialog, which stores the file as a static upload rather than importing it as a document. Use New and then Import files… when you want an HTML file to become an editable document.

Use Make malleable on a static page#

If you imported a static HTML page that does not include ClayJS yet, you can add ClayJS to it from its actions menu:

  1. Open the … actions menu on the document row in your file list, or open the document’s … menu in the workspace editor.
  2. Click Make malleable.
  3. In the Make malleable dialog, click Make malleable to confirm.

Hyperclay saves a backup of your current file first, then splices two script tags right before the closing </body> tag without reformatting the rest of your file:

  • https://clayjs.com/v1/clay.js (with ?plugins=cms,sortable,undo,ai-edit added automatically if the page already carries CMS rules)
  • https://clayjs.com/v1/clay-ui.js

Once the workflow finishes, the page can save changes to itself and the Make malleable item disappears from the menu. The page opens in view mode, as every ClayJS document does. Press Cmd+Shift+E (Ctrl+Shift+E on Windows and Linux) to switch to editing, or load the menu plugin to give the page an Edit switch.

Make malleable adds the ClayJS runtime and saving support, but it does not decide which elements on your page are editable. To make specific headings, paragraphs, or lists editable, either add ClayJS attributes yourself in the code editor (see ClayJS attributes and CMS) or use AI to wire up editable fields (see Use AI).

Requirements for Make malleable#

  • You must have code-editing permission on the document (the document owner or a team editor on an active paid plan).
  • The page must have a <body> tag. Pages that use <frameset> without a <body> must be converted to a standard HTML page in the code editor first.
  • The page must not already load ClayJS or load multiple copies of the library.
  • The page cannot be managed by a collection.