Get started

Your first file

You downloaded an app. In about five minutes you will have something better: a file of your own that opens like a web page and saves like a document. No account, nothing to configure, nothing to learn first.

1 Install the app

One download, once. It is free and there is no account.

On a Mac, open the disk image and drag HTML Clay into Applications, then open it once. Look up by the clock: a small icon in the menu bar is the whole app. There is no window.

On Windows, unzip the download and run htmlclay.exe once. It sets up .htmlclay files for your account, with no administrator prompt, and sits in the system tray.

On Linux, unpack the tarball and run bash install.sh. It installs into ~/.local/bin and never asks for sudo.

Linux also wants zenity or kdialog installed, because those draw the permission dialogs. Without either, a file from outside a folder you trust is refused rather than asked about.

Download HTML Clay

2 Make the file

Copy this. All of it. It is a checklist, and its first three items are the rest of this page.

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;
    }
    label {
      display: flex;
      gap: 0.6rem;
      padding: 0.3rem 0;
    }
  </style>
</head>
<body>
  <h1 editable>My list</h1>

  <label>
    <input type="checkbox" persist>
    <span editable>Make my first file</span>
  </label>
  <label>
    <input type="checkbox" persist>
    <span editable>Check something off</span>
  </label>
  <label>
    <input type="checkbox" persist>
    <span editable>Close the tab, then open the file again</span>
  </label>

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

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

Paste it into any plain text editor and save it as my-list.htmlclay, on your Desktop.

Two editors need a nudge. TextEdit on a Mac has to be in plain text mode first: the Format menu, then Make Plain Text. When it asks about the file ending, keep .htmlclay. Notepad on Windows needs Save as type set to All files, so it does not quietly add .txt.

You do not need to read the file to use it. If you do read it, you will find ordinary HTML: a heading, three checkboxes, a place for notes, and one script tag at the bottom that teaches the page how to save itself.

Already have an .html file you like? Rename it to .htmlclay and it opens the same way, and it needs that same script tag before its own edits will save.

3 Open it, and check something off

This is the part worth the whole page.

Double-click my-list.htmlclay. It opens in your everyday browser, in an ordinary tab, with the shortcuts you already use. The address starts with 127.0.0.1, which is your own computer: the page is reaching you from your own disk, not from the internet.

Now check the first box. You did just make your first file.

There is no save button. A moment after you stop, the page writes itself back into my-list.htmlclay, and a small chip notes that it saved. Click an item and retype it. Jot something in the notes area.

Then check the third box, close the tab, and double-click the file again.

Everything is still there. The checked boxes, your words, all of it. Not in an account and not somewhere in your browser: in the file, on your Desktop, written into the HTML itself.

Prove it to yourself. Open that same file in a text editor. The line you checked now reads:

my-list.htmlclay
  <label>
    <input type="checkbox" persist checked>
    <span editable>Make my first file</span>
  </label>

That word checked was not there a minute ago. Your click put it in the file. From here you can email the file, back it up, or drop it in any folder, and it takes its contents with it.

If it did not work

4 Trust the folder it lives in

Click the HTML Clay icon in your menu bar or system tray, choose Trusted Folders, and pick the folder your file is in. Every .htmlclay file in that folder then opens ready to edit, including ones you add later, and the files can link to each other like the pages of a small private site.

Stop trusting a folder from the same menu, and that permission ends immediately.

Why it needs an app at all

A browser cannot write to your disk. That is the rule the whole web is built on, and it is a good rule. HTML Clay works around it in the smallest way there is: it hands your file to your browser, and when the page has changes to save, it writes them back into the same file. Nothing is uploaded, because there is nowhere to upload to.

That is the entire app. It adds one ability to an HTML file, the ability to save into itself, and takes nothing away. Rename my-list.htmlclay to my-list.html and it opens in any browser on any machine, list and all. It just stops saving. Nothing in it depends on this app.

Make it yours

The list is a starting point, not the point.

The fastest change needs no tools: click any text in the page and retype it. "My list" can become "Packing for Portugal" right there in the tab.

The more interesting change is one level down. Leave the tab open, open my-list.htmlclay in a text editor, copy one of the <label> lines, paste it below the others, and save. Watch the tab: the new checkbox appears in the open page on its own, with no reload. The file is the app, so anything that edits the file edits the app, including you, in whatever editor you like.

Three attributes cover most of what people want:

Put this onWhat it does
editableOn any element. You can click into it and type, with a small formatting toolbar.
persistOn a checkbox, text field, or dropdown. Its value is written into the file, so it survives.
autosaveOn the <html> tag. Saves on its own once your edits settle. Cmd+S and Ctrl+S always work too.

And it does not have to be a list. A journal, a recipe box, a habit tracker, a small game: the home page shows the kinds of things people make, and every one of them is a single HTML file just like yours.

Building one from scratch is the job of clayjs, the small library that last line loads. Its own walkthrough is at clayjs.com/get-started, including a ready-made prompt you can hand to an AI to have it build a file for you.

That page teaches you to write the file. This one handed you a finished one.

Good to know

A few things worth hearing from us rather than discovering.

The first open wants a connection. The starter fetches its editing library from clayjs.com when it loads. The app itself never needs the internet, and if you want a file that works on a plane from the very first open, keep a copy of that library beside the file and point the script tag at it.

You can send it to anyone. Someone without HTML Clay renames it to .html and can read and use the page. Their changes just will not be written back into the file.

You cannot really wreck it. Every save keeps a complete copy of the version before it. Choose Backups from the tray icon to see them: plain HTML files you can open anywhere, with or without this app.

One attribute appears in your file. After the first save you will see htmlclayid on the <html> tag. It is how your history stays attached to the file when you rename or move it.

Links open read only. Double-clicking a file makes it editable, because you chose it. Reaching one through a link does not: it opens read only, with an offer on the page to trust its folder.

Only inside your home folder. A file outside it does not open at all, and no dialog offers to make an exception. The exact boundary is on the features page.

Where next

One file. Yours.

Make a second one whenever you like.

Download HTML Clay