# 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.

Source: https://hyperclay.com/docs/making-malleable-documents/

You make malleable documents with [ClayJS](https://clayjs.com/docs/), 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](https://htmlclay.com/docs/), [Hyperclay Local](https://hyperclaylocal.com/docs/), or your own server.

## Learn ClayJS

- [ClayJS docs](https://clayjs.com/docs/): Read the complete guide and API reference for building with ClayJS.
- [ClayJS quick start](https://clayjs.com/docs/guide/quick-start/): Turn an HTML file into a self-saving document in a few minutes.
- [A document explained line by line](https://clayjs.com/docs/guide/walkthrough/): See a complete ClayJS document explained line by line.

## 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](https://hyperclay.com/docs/uploads/). See [Import and export](https://hyperclay.com/docs/import-export/) for full details.

> [!NOTE]
> 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](https://hyperclay.com/docs/uploads/) 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](https://clayjs.com/docs/plugins/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](https://clayjs.com/docs/plugins/menu/) 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](https://hyperclay.com/docs/code-editor/) (see [ClayJS attributes](https://clayjs.com/docs/attributes/) and [CMS](https://clayjs.com/docs/plugins/cms/)) or use AI to wire up editable fields (see [Use AI](https://hyperclay.com/docs/guide/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](https://hyperclay.com/docs/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](https://hyperclay.com/docs/collections/).
