Deploying
Deploying
Three supported targets, plus “anywhere you can host static files”.
GitHub Pages (recommended for personal sites)
The simplest path — and on the Mac it’s guided: the inspector’s Publish Site tab is a
four-step checklist (account → repository → content → deploy) that shows live where you
stand. Connect GitHub, type ANY owner/repo name — it doesn’t have to exist; the first
deploy creates it (public — free Pages needs that) and enables Pages — publish at least
one note or artifact, and deploy. Tick “Deploy automatically when published notes change”
and that first deploy is the last one you trigger by hand.
From the CLI, pre-requisites:
A GitHub repo (public, or private with paid Pages). Lettuce creates it for you if it doesn’t exist yet.
A
gh-pagesbranch (the default) — Lettuce pushes the built site there.A GitHub PAT. Use a fine-grained PAT with Contents: Read/Write on the target repo. Pass it with
--token, or set$GITHUB_TOKENin your environment.
One command does it all — build, push, enable Pages, print the live URL:
lettuce deploy --repo DrBaher/my-notes --token "$GITHUB_TOKEN"
Useful flags: --branch (default gh-pages), --message (commit message, default Publish from Lettuce), --private (create the repo private rather than public), --all (include unpublished notes), and --contact (owner email for the footer). The vault is the first positional argument (defaults to the current directory).
Within ~30 seconds GitHub Pages serves it at https://<user>.github.io/<repo>/. The command prints the live URL when it finishes.
Custom domain
Pass the absolute URL with --base-url so OpenGraph tags and the sitemap point at your domain:
lettuce deploy --repo DrBaher/my-notes --token "$GITHUB_TOKEN" \
--base-url "https://notes.baher.com/"
Then set your domain’s DNS to CNAME → <user>.github.io and enable HTTPS in the GitHub repo settings. (Lettuce does not manage DNS or write a CNAME file — configure the custom domain in the GitHub repo’s Pages settings.)
Vercel from the app
The Mac’s Publish Site tab can deploy to Vercel directly, over Vercel’s API, with no git and no
build settings. Pick Publish to ▸ Vercel, paste a Vercel token (Account Settings ▸ Tokens), name
a project (Lettuce creates it on the first deploy) and deploy. The live address is the project’s
production domain, <project>.vercel.app unless you added your own.
Two things to know:
Vercel Authentication. Many Vercel accounts switch on “Vercel Authentication” for new projects, which sends every reader without access to your Vercel team to a Vercel login page. Lettuce turns it off on a project it creates, and when you choose one of the protection options below (they replace it). On a project you made yourself with no protection chosen here, Lettuce leaves it alone and tells you after the deploy, because it may be deliberate.
Commercial use. Vercel’s free Hobby plan is non-commercial under Vercel’s terms. Business content needs a paid plan.
Who can read it
Under Publish Site ▸ Who can read it:
Anyone with the link (the default).
Password (checked by the server), Vercel only. Readers get the browser’s password prompt and receive no page at all without it. Change the password here and redeploy to rotate it.
Passphrase (pages encrypted), any host including GitHub Pages and a published folder. Every page, image, the search index and the link graph are encrypted, and unlock in the reader’s browser. Use Generate for the passphrase: the encrypted files can be downloaded by anyone, so a short passphrase can be guessed offline. Typed ones need at least 16 characters.
Every way of deploying applies the choice: the Deploy button, auto-deploy, the iPhone’s Publish
button and lettuce deploy (which reads it from the vault’s saved settings). If the choice can’t be
applied, the deploy stops instead of publishing an open site. After a Vercel deploy, Lettuce asks the
live site whether it is protected and reports a failure if it opened without the password.
On a passphrase-protected site, pages get unguessable addresses (p-<hash>.html). The “View
online” links in the app and on the iPhone know those addresses, so copy links from there. Two
limits: the unlock is remembered for the browser tab, and on a <user>.github.io project site that
memory is shared with every other project site on the same account, so don’t host a protected site
next to pages you don’t control. And anyone who has had the passphrase keeps what they opened.
Vercel through git
Vercel is what powers https://lettuce.drbaher.com. Vercel auto-deploys from a git repo, so the flow is “build locally, push to git, Vercel picks it up”:
Make a Vercel project pointing at your vault’s repo.
Set its Root Directory to
_site/(the defaultlettuce publishoutput, so Vercel ignores your sources).Set the Build Command to empty and Output Directory to
.(Vercel serves the static files as-is).Run
lettuce publishbefore each commit (or use a git pre-commit hook).
For per-commit auto-publish, add to your repo root:
# .git/hooks/pre-commit
#!/usr/bin/env bash
lettuce publish
git add _site/
S3 + CloudFront (or any static host)
lettuce publish
aws s3 sync _site/ s3://my-bucket/ --delete --cache-control "max-age=300"
aws cloudfront create-invalidation --distribution-id E123 --paths "/*"
Lettuce doesn’t ship S3 integration directly — but lettuce publish produces a plain directory you can sync anywhere.
Self-hosting
Just rsync _site/ to a server with any HTTP daemon (nginx, caddy, Apache).
Caddy is the easiest:
notes.baher.com {
root * /var/www/notes
file_server
try_files {path} {path}/ /404.html
}
What gets pushed
The lettuce deploy command:
Builds the site into a temporary directory (the same build as
lettuce publish).With
--repo+ a token: creates the GitHub repo if needed, force-pushes the built tree to the target branch, enables Pages, and prints the live URL.With
--remote URLinstead: force-pushes the built tree to that bare git remote on the target branch.
Your source vault is not pushed — only the built site.
Continuous deploy
lettuce deploy is a one-shot command, so the simplest “every night” setup is your operating system’s own scheduler — a cron entry or a launchd job — that runs the command on a timer:
# crontab: rebuild and deploy at 04:00 daily
0 4 * * * cd /path/to/vault && lettuce deploy --repo DrBaher/my-notes --token "$GITHUB_TOKEN"
Lettuce’s own .lettuce/schedules.yml is for agent work, not shell commands: each rule fires a maintenance action: (such as maintain or lint-semantic) or splices a > [!ai] <prompt> directive into a target note for a connected MCP agent to pick up — it cannot run lettuce publish or lettuce deploy itself. Use the OS scheduler above for unattended deploys.
Related
Deploy automatically
Turn on “Deploy automatically when published notes change” in the publish sheet and Lettuce watches your published surface — the notes and HTML artifacts that are on the site, plus anything newly marked published — and pushes on its own: a few minutes after you stop editing (so a writing session becomes one deploy, not twenty), never more than every 15 minutes, and only when something on the site actually changed. Unpublishing or deleting a published note also triggers a deploy, so pages come down automatically too.
It runs from the Mac that holds your deploy token (the app, or its always-on background server — whichever is up; they coordinate so nothing is pushed twice). A failed push (offline, revoked token) is retried on the next cycle. Combined with the artifact recipe, “make this dashboard public” becomes: Claude writes the tagged artifact → Lettuce notices → your GitHub Pages site updates — no manual step anywhere.