Get started

Your first file

Install HTML Clay, copy a checklist, change it, then reopen it. Your changes will be in the file on your disk, not in an account or browser storage.

1 Install HTML Clay

The download is free and there is no account.

Choose your download

On a Mac, open the disk image, drag HTML Clay into Applications, and open it once. The app lives in the menu bar and has no main window.

On Windows, unzip the download somewhere you will keep it, then run htmlclay.exe once. It registers .htmlclay files for your account without an administrator prompt, then stays in the system tray.

On Linux, unpack the tarball, open a terminal in that folder, and run bash install.sh. The default installation goes in ~/.local/bin.

2 Make the file

Use a plain text editor, then copy the complete checklist below.

In TextEdit on a Mac, choose Format, then Make Plain Text. In Notepad on Windows, set Save as type to All files.

Keep your internet connection on while using this starter. It loads its editing library, ClayJS, from clayjs.com. HTML Clay does not upload your file.

my-list.htmlclay

<!DOCTYPE html>
<html lang="en" autosave>
<head>
  <meta charset="utf-8">
  <title>My list</title>
  <style>
    body {
      font-family: system-ui, sans-serif;
      max-width: 30rem;
      margin: 3rem auto;
      padding: 0 1rem;
    }
    .item {
      display: flex;
      gap: 0.6rem;
      padding: 0.3rem 0;
    }
  </style>
</head>
<body>
  <h1 editable>My list</h1>

  <div class="item">
    <input type="checkbox" persist aria-labelledby="item-1">
    <span id="item-1" editable>Make my first file</span>
  </div>
  <div class="item">
    <input type="checkbox" persist aria-labelledby="item-2">
    <span id="item-2" editable>Check something off</span>
  </div>
  <div class="item">
    <input type="checkbox" persist aria-labelledby="item-3">
    <span id="item-3" editable>Close the tab, then open the file again</span>
  </div>

  <div editable>
    <p>This part is for notes. Click anywhere and type.</p>
  </div>

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

Paste it into the editor and save it on your Desktop as my-list.htmlclay. If the editor asks about the extension, keep .htmlclay.

3 Open it and make a change

Open my-list.htmlclay from your Desktop. It opens in your default browser. An address beginning with 127.0.0.1 means HTML Clay is serving the page from your own computer.

Check the first box, edit the second item, and type a note. Wait until a small chip in the bottom right says Saved. There is no save button.

Close the tab, then open the file from your Desktop again. Your checked box and words are still there because they were written into my-list.htmlclay.

See it in the file. If my-list.htmlclay is still open in your text editor, close it without saving. Then reopen it. The first checkbox now contains checked:

my-list.htmlclay

  <div class="item">
    <input type="checkbox" persist="" aria-labelledby="item-1" checked="">
    <span id="item-1" editable="">Make my first file</span>
  </div>

Browsers write bare attributes such as persist as persist="". HTML Clay also adds documentid to the root <html> tag for backup history. Both are normal.

If it did not work

You see code instead of a checklist: save the file as plain text and confirm its name ends in .htmlclay, not .htmlclay.txt.
The file does not open with HTML Clay: on Windows, run htmlclay.exe again. On Linux, rerun install.sh. On a Mac, select the file in Finder, then choose File, Open With, and HTML Clay.
Nothing is editable or saves: reconnect to the internet, then reload the page.

How saving works

A browser cannot write to your disk by itself. HTML Clay serves the file to your browser and writes each save back into that file. ClayJS runs inside the page and turns your edits into HTML for HTML Clay to save.

The three attributes

These did the work in this file.

Attribute	What it does
`editable`	On a heading, paragraph, span, or div, lets you click into it and edit its contents.
`persist`	On a checkbox, text field, textarea, radio button, or dropdown, writes its value into the file.
`autosave`	On the `<html>` tag, saves after edits settle.

Command+S on a Mac or Control+S elsewhere saves at once.

Edit visible text directly in the browser. To change the structure, close the browser tab, edit my-list.htmlclay in your text editor, save it, then open the file again.

Good to know

The file remains ordinary HTML. Rename it from .htmlclay to .html and a browser can open the saved contents. Without HTML Clay, further changes are not written back into the file.

HTML Clay keeps recent backups when it can. If a change goes wrong, choose Backups from the menu bar or tray icon to find earlier copies of the file.

Files must stay inside your home folder. HTML Clay refuses to open a file outside it.

Where next

Build your own file. Learn the ClayJS attributes and start from plain HTML.
Use several files together. Learn about Trusted Folders, backups, live sync, and the safety boundary.
Let a local program edit the file. Connect a script or coding agent to the file.

One file. Yours.