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

Source: https://htmlclay.com/docs/build-from-source/

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.

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