HTML Clay
  1. HTML Clay
  2. Docs
  3. Host reference
  4. Build from source

Build from source

What you need to build HTML Clay from its repository, what each top-level package does, and three things about the repo that are easy to trip over.

HTML Clay is a Go application built from a checkout, and its repository layout says what each part of the app does.

Building the app from source#

Go 1.26 or later. Linux and Windows build as pure Go; macOS builds use cgo for the system tray and Finder integration.

plaintext
cmd/htmlclay/        The executable. main.go starts and stops it, sites.go owns the site registry,
                     folders.go the trusted-folder list, open.go hands a file to the browser,
                     recovery.go the remembered-port page, wire_cli.go the `htmlclay wire` CLI
internal/server/     HTTP server, request handlers, security middleware, the wire, live sync
internal/session/    Token generation, file to token mapping, held read roots
internal/trust/      Which folders may be trusted, and on whose say-so
internal/dataapi/    Reading a document as JSON, with its vendored conformance corpus
internal/versions/   Save history
internal/browser/    Opening a URL in the system's default browser
internal/htmlutil/   Inject and strip savetoken and documentid on the <html> tag
internal/config/     Settings in the OS config dir
internal/platform/   Single-instance lock, Start on Login, file associations, native dialogs
internal/tray/       System tray icon and menu
internal/logging/    File logger with 10 MB rotation
internal/update/     Version check against download.htmlclay.com
packaging/           Per-OS packaging assets and build scripts
website/             htmlclay.com, deployed from this repo

Three things about the repository are easy to trip over:

  • The website deploys itself on every push to main. htmlclay.com is a Cloudflare Worker fed by a git integration, not by CI and not by a manual wrangler deploy. There is no deploy command to run, and adding one only races the integration.
  • Download links are stamped after CI, not during the version bump. scripts/stamp-website.js writes the version into website/index.html, anchored on the data-version, data-mac-dmg, and data-sha256 attributes. Stamping during the bump would publish links to a dmg CI has not uploaded yet.
  • htmlclay-release-info.json on R2 is not a website file. It is the feed the in-app update checker polls, and its URL is compiled into every shipped binary. Removing it would silently and permanently break update checks for installs already in the wild.