KilnHow Kiln works
One idea: your site is the CMS.
Kiln edits static sites in place. Your pages stay plain HTML in a GitHub repository connected to a host that redeploys on every push (Cloudflare Pages, Netlify, Vercel, GitHub Pages). When an editor changes something, Kiln fetches the page's own HTML from GitHub, splices the change at exact source offsets, and commits. There is no database, no content files, no build pipeline — every edit is a commit, and the auto-deploy is the publish button.
Two small pieces make it work: a Cloudflare Worker that handles sign-in and coordinates every commit, and a GitHub App that grants repo access. Who runs those two pieces is the only difference between the plans:
- Self-hosted — you run both. Free forever, open source (AGPL-3.0).
- Kiln Cloud — we run both; you keep your repo and host. $4.99/mo per site.
- Fully managed — we run everything, hosting and setup included. $14.99/mo per site.
The editor is identical on all three. See Product for the full comparison.
Install: self-hosted
You run the sign-in & commit worker and your own GitHub App. Free forever. About ten minutes with the wizard.
npx github:kilncms/kiln in your site's folder. The wizard does every scriptable step and waits while you click the few buttons only a human can. Already installed? npx github:kilncms/kiln doctor health-checks everything. The steps below are what the wizard does, written out — read them to understand the moving parts, but pick the command or the manual path, not both.1 · Host your code on GitHub, your site anywhere
- Push your static site (plain HTML, CSS, JS) to a GitHub repository — this is where your code and content live.
- Connect the repo to a host that auto-deploys on each commit. Cloudflare Pages is recommended (free, commercial use allowed): in the Cloudflare dashboard go to Workers & Pages → Create → Pages → Connect to Git, pick your repo, leave build command empty and output directory
/, then Deploy. - Vercel, Netlify, and GitHub Pages work the same way. Any host that redeploys from a Git push is a valid Kiln host.
2 · Deploy your sign-in worker
This worker is yours. It runs on Cloudflare Workers (free tier) and is the piece that signs editors in and coordinates every commit to your repo. By hand it is four commands:
git clone https://github.com/kilncms/kiln && cd kiln
npm install
cd worker
npx wrangler kv namespace create KILN # paste the printed id into wrangler.toml
npx wrangler deployNote the URL it prints, like https://kiln-auth.yourname.workers.dev. Because the worker lives on a plain workers.dev URL, OAuth callbacks are registered automatically at app-creation time in the next step.
3 · Register your own GitHub App — one click
- Open
https://YOUR-WORKER.workers.dev/setupand press the button. The app registers under your account via GitHub's manifest flow and the worker captures its credentials — you never copy a secret. - Click Install, choose Only select repositories, and pick your site's repo. Kiln can only ever touch repos you select.
- Add your site's URL to
ALLOWED_ORIGINSinworker/wrangler.toml, then redeploy the worker once more.
4 · Make your HTML editable
Create /assets/kiln-config.js (see Configuration), copy kiln.js, kiln-editor.js, and kiln-features.js from the Kiln repo's dist/ into your site's /assets/ (kiln-features.js is lazy-loaded by kiln.js for galleries, filters, and calendars — leave it out and those 404 for visitors), and add two script tags at the end of <body> on every page:
<script src="/assets/kiln-config.js"></script>
<script src="/assets/kiln.js" defer></script>Then annotate what's editable (the one step the wizard can't decide for you, though an AI can — see the annotation reference):
<h1 data-cms="headline">Welcome</h1>
<img data-cms="hero" data-cms-attr="src" src="/img/hero.jpg">
<div class="cards" data-cms-repeat="services"> …repeatable blocks… </div>
<div class="nav-links" data-cms-menu="main"> …site menu… </div>5 · Sign in and edit
Push everything. After the deploy, visit yoursite.com/kiln and choose Continue with GitHub. Outlined text is editable — click it, type, hit Publish. About a minute later it's live.
Optional: Google sign-in for editors and members
Let clients, teammates, or community members in without GitHub accounts. In the Google Cloud console, create an OAuth 2.0 Client ID of type Web application and set the authorized redirect URI to https://YOUR-WORKER/google/callback (the worker URL from step 2). Then store its credentials as two secrets on your worker:
cd worker
npx wrangler secret put GOOGLE_CLIENT_ID
npx wrangler secret put GOOGLE_CLIENT_SECRETA Continue with Google button now appears on your /kiln sign-in screen. Add editors and members by their Google email under People & access; only addresses you have added can get in.
Updating Kiln
When a new Kiln version ships, run npx github:kilncms/kiln update in your site's folder. It re-copies the latest editor bundles into your site and commits them; your host deploys the update like any other change. At any time, npx github:kilncms/kiln doctor health-checks the worker, app, config, and annotations.
Set up: Kiln Cloud
We run the sign-in & commit worker and the GitHub App; you keep your repo and host. $4.99/mo per site, 7-day free trial. Prefer this as one skimmable page? See Get started.
Prep your repo with one command. Your site needs to be a GitHub repo. In your project run npx github:kilncms/kiln, which adds the Kiln scripts and config. Commit and push. Make sections editable by clicking them in the browser (Make editable), auto-tag a reviewable first pass (npx github:kilncms/kiln tag; tables are never made repeatable, though cell text can still be tagged; undo with git checkout), or bulk-tag with your AI (annotation reference). Connect a host that auto-deploys on push if you haven't (Cloudflare Pages recommended).
Install the Kiln GitHub App. At github.com/apps/kiln-cms, choose Only select repositories and pick your site's repo. That's the only button you press, and the app can only touch the repo you select.
Sign up and subscribe. Sign in at app.kilncms.com, add your site (repo + live URL), and start the 7-day free trial. Payments are processed by Lemon Squeezy; cancel any time.
Edit your live site. Visit yoursite.com/kiln, sign in, edit on the page. Every change commits to your own repository. Editing, history, drafts, scheduling, and Google sign-in for editors all run against our worker — you deploy and maintain none of it.
kiln-cms app installed on your repo, not a fresh app you registered. Everything else (repo, host, editor) is the same. Switching to self-host later means deploying your own worker and app; your repo never moves.Set up: Fully managed
We set your existing site up on Kiln for you — hosting, worker, app, and wiring. $14.99/mo per site, 7-day free trial.
Start your trial and point us at your site. Sign up at app.kilncms.com and tell us where your existing site lives — its GitHub repo and live URL. If your AI built the site, that's enough. This is the only step that's yours.
We set it up. Hosting, the worker, the GitHub App on your repo, and the standard editing setup so your pages are editable. You don't touch any code.
Sign in and edit. We hand you the link. Sign in at yoursite.com/kiln, add your editors by Google email, and edit by clicking the page.
Standard setup (wiring + auto-tag) is included. Concierge setup & tagging (hand-tagging everything including tables, access configured with you, one revision round) is an optional one-time $399: email [email protected]. And even though we run the hosting, your pages remain plain HTML in your own repo: leaving is deleting two script tags and pointing the repo at any host.
Signing in & out
There is no edit button on the site. To edit, go to yoursite.com/kiln.
Choose Continue with GitHub. You get every capability on this page.
Choose Continue with Google, using the address the owner added. No GitHub account needed.
After sign-in you land on the site with editing on, and every page stays editable until you finish. A round floating Kiln button sits in the corner — hover or tap it for the menu, and drag it anywhere. Prefer a fixed bar across the top? Open Settings and switch to Top bar.
Done editing hides Kiln so you can browse normally (you stay signed in; a small ✎ Resume editing button brings it back). Sign out ends the session.
Publishing & undo
Edits are staged on the page, then published together as one save. Undo works like Canva.
As you change things, each edit gets a yellow outline and the Publish button counts them (Publish 3 edits) — nothing is live yet. Hit Publish and Kiln writes all staged edits to your repository in one commit; your host rebuilds and the change is live about a minute later. Kiln watches and tells you the moment it's live. You can keep editing while a publish is in flight; anything you change mid-publish simply stays staged for the next one.
Undo & redo
- ⌘Z / Ctrl+Z undoes your last staged change — a text commit, a block move, an image swap, an added section, a restore. ⌘⇧Z / Ctrl+Y redoes it. Small ↶ ↷ buttons also appear by the Kiln button whenever there's something to undo.
- While you're typing inside a field, the browser's normal text undo applies; Kiln's undo works at the level of whole saved changes.
- Esc (or Revert) throws away the edit you're currently in. Clicking away keeps it staged.
- Discard edits throws away everything staged and reloads.
- If your browser crashes with staged edits, Kiln offers to restore them on your next visit.
Editing text
Click outlined text to turn it into a live editor with a toolbar.
- Style menu: paragraph / heading / subheading / quote, plus any site styles your developer defined, so text stays on-brand.
- B / I / U, bullet and numbered lists, and Clear to strip formatting.
- Link (chain icon): select text first, then paste a URL or a path like
/contact.html. - Image and 📄: insert a picture or an uploaded document at the cursor.
- ↻ clock: this section's own history — see History.
The toolbar is draggable — grab the ⠿ handle if it's in your way. Editing a link also shows a destination box and Attach file… to point it at an uploaded PDF. To follow a link while editing, Cmd/Ctrl-click it. Clicking into a field and back out without changing anything never creates a phantom edit.
Images & resizing
Click an editable image for its toolbar; drag the corner handle to resize.
- Replace image… uploads a new picture, auto-compressed for the web so a big phone photo doesn't slow the page.
- Drag the ● corner handle to resize how the image displays. Kiln keeps the original at high resolution and publishes a web-optimized copy at the size you chose — so if you enlarge it again later, the copy is remade from the original and never degrades.
- The text box on the toolbar is the image's alt text — a one-line description for screen readers and search engines. Fill it in.
Right after upload you see a local preview; the file itself is committed with your next Publish (nothing orphaned if you discard). Pictures inside a paragraph get their own width controls and a remove button when clicked.
Documents
Put a PDF or file on a page as a link, a chip, or a card.
- Attach to a link: click the link, then Attach file….
- Insert in text: while editing, click 📄, pick the file, then choose how it appears — a plain text link, a bordered chip, or a card with the file type and size. Rename the label before inserting.
- When clicked: choose whether the document opens in a new tab (good for PDFs people read) or downloads directly.
Files live in your repo under assets/files/ (on a members-only page they go to the gated members/files/, so only signed-in members can open them). The limit is 15 MB per file.
Blocks, lists & tables
Repeating things — cards, team members, document lists, schedule rows.
Hover any block and controls appear in its corner:
- ↑ ↓ move it, or drag the block to reorder.
- ＋ duplicates it (then edit the copy). ✕ removes it.
- 🏷 tags it (next topic).
- + Add block under the list appends a copy, ready to edit.
This works for table rows too — a schedule marked as a block list gets the same controls per row, and Kiln preserves table structure exactly.
Tags & filters
Tag blocks and visitors get filter buttons automatically.
Press 🏷 on any block and type comma-separated labels, like new, used, upcoming. The moment one block in a list is tagged, a filter-button preview appears above the list while you edit — All plus one pill per tag. Publish, and every visitor gets those same buttons; clicking one hides everything without that tag. No setup beyond the tags.
Photo galleries
A thumbnail grid for editing; a full-screen viewer for visitors.
- + Add photos takes several images at once — each is compressed and added to the grid with an editable caption. Reorder and remove like any block.
- ⚙ Gallery options sets the thumbnail size (small, medium, or large) per gallery.
- No gallery on the page yet? ＋ Add a gallery or events in the Kiln menu drops a ready-to-fill section onto the page (staged like any edit — live only when you publish).
Visitors see the thumbnail grid; clicking a photo opens it full-screen with prev/next paging, captions, arrow keys, and swipe.
Events & calendar
List events; visitors switch between list and calendar views.
- + Add event opens a form — title, date, start/end time, location, an optional link, and details. Kiln keeps the list in date order.
- 📅 on an event reopens the form to change it.
Visitors get List / Month / Week / Day buttons above the events. Month view is a real calendar grid; clicking an event shows its details. It's all rendered from the same content you edited — there's no separate calendar to keep in sync.
Posts, pages & the menu
Add to the site and manage navigation.
- ＋ New post or page creates a blog post (article + listing card, in one commit) or a standalone page from your template. Kiln gives you the link the moment it's live.
- Site menu edits your navigation (add, rename, reorder) and applies it to every page in one publish. Add new pages here so people can find them.
- Page settings edits the browser-tab title, the search-result description, and the social-share image. It's also where an owner can delete a page.
Drafts & scheduling
Work privately, publish later.
- Save as draft stores staged edits privately — nothing goes live. Next time the page is opened in Kiln, it offers to resume, publish, or delete the draft.
- Schedule for later… publishes your staged edits automatically at a time you pick. Your edits re-apply against the live page at that moment, so anything published in the meantime is kept.
History & rolling back
Every publish is a saved version. Undoing always previews first — nothing goes live until you Publish.
History & restore in the menu lists this page's versions in plain language (“Edited hero headline and 2 more”, “Added 3 photos”), each with who and when. Two things you can do with any version:
- Undo this change — takes back just what that one publish changed, leaving everything since intact. Works on the newest (live) item too.
- Go back to this — returns every section of the page to how it was at that point.
Either way, Kiln first shows the result on the page itself with a bar across the top: Keep — then Publish stages it like any other edit (⌘Z undoes it), Cancel puts everything back. Nothing touches the live site until you hit Publish.
One section's history
Click into any section and press the ↻ clock on its toolbar to see just that section's past versions, with a text preview of each. Pick one to preview it in place — same Keep / Cancel flow. This is the fastest way to fix “someone rewrote this paragraph last week and I want the old one back.”
Find & replace
Change a phrase everywhere at once.
Find & replace scans your site's pages (up to 100 HTML files) for a phrase, like an old phone number, a name, or an address, shows where and how many times it appears, and replaces them all in one change. Preview first, then Replace all.
People & access
Owner only. Add editors and members by Google email; scope editors to pages and sections.
- Editor — edits content. Scope them with ▾ Choose pages (a checklist of your site's pages and folders) and ▾ Choose sections, a per-page list of the site's editable sections, each shown with the first words of its content so you can tell what it is. Outside their scope, editors see the page read-only with a note about where they can edit.
- Member — no editing; can view members-only pages and files after signing in.
- Tools — per editor, choose which menu tools they get (drafts, history, new posts, scheduling, site menu, find & replace, make-editable). Editing text and images is always allowed; People & access and site Settings stay owner-only.
- Access lasts 1–360 days or never expires. Remove revokes access immediately, including any open session.
Changes editors publish are attributed to them by name in the site's history. When several people are signed in, the menu shows who's online and which page each person is on.
For members
A member signs in by visiting any members-only page (or the members sign-in page) and pressing Continue with Google, using the exact Google email the owner added. That unlocks the gated pages and files for the number of days the owner set; when it expires, they simply sign in again.
Making things editable
Owner only. Turn any part of the page into something editors can change.
Open ✨ Make text/images editable in the Kiln menu. Everything you hover gets a green outline; click an element and choose what it becomes:
Click-to-edit, with or without formatting.
Click to replace, resize, set alt text.
Add / reorder / remove / tag the items inside.
Managed navigation, synced across pages.
Kiln writes the change into your site's actual HTML (committed like any edit) and the element is editable right away. Click something already editable (red outline) to remove editing from it; the content stays, only the handle goes.
Adding new galleries or event lists is its own menu item, ＋ Add a gallery or events, because those add a new section to the page rather than making an existing one editable.
Editing at the same time
Two people, one page, no lost work.
When someone else has the page open in Kiln you'll see a note: "Susan is also editing this page." Edit different things and both save cleanly. Edit the same text and whoever publishes second gets a warning naming the overlap, with two honest choices: Reload & review (your edits are kept and offered back) or Publish mine anyway. Nothing is ever silently lost — every version stays in History.
Configuration reference
/assets/kiln-config.js — the one config file.
window.KILN = {
repo: 'you/your-site-repo', // GitHub owner/name
branch: 'main', // branch Kiln commits to
worker: 'https://kiln-auth.you.workers.dev', // your (or our) sign-in worker
styles: [], // site CSS classes for the Style menu
};| Key | Required | What it does |
|---|---|---|
repo | yes | The GitHub repository (owner/name) Kiln reads from and commits to. |
branch | no | Branch to commit to. Default main. |
worker | yes | URL of the sign-in worker. Self-host: your workers.dev URL. Kiln Cloud / managed: ours (set for you by the prep command). |
styles | no | Array of {label, class} entries exposed in the text toolbar's Style menu, so editors can only apply on-brand styles. |
root | no | Subfolder of the repo the site is served from, if not the repo root. |
home | no | Path of the homepage file if it isn't index.html. |
siteName | no | Display name shown on the /kiln sign-in screen. |
entry | no | Set false to disable the /kiln entry page handling, or a string path (e.g. '/edit') to use a custom entry path instead of /kiln. |
auth | no | Sign-in options. auth: { google: false } hides the Continue with Google button on the sign-in screen. |
Annotation reference
Plain HTML attributes mark what's editable. Your AI (or the wizard) usually writes these.
| Attribute | On | Makes it |
|---|---|---|
data-cms="key" | any text element | Click-to-edit rich text. The key names the section (e.g. hero_headline) — keys are per-page and show up in history and access scoping. |
data-cms-plain | a data-cms element | Plain text only — no formatting toolbar (dates, prices, kickers). |
data-cms-attr="src" | <img> | A swappable image: replace, drag-resize, alt text. |
data-cms-repeat="key" | a container | Repeating blocks — every child becomes add/duplicate/reorder/remove/tag-able. Works on lists, card grids, and table sections. |
data-cms-menu="key" | your nav | The managed site menu, editable once and synced across every page. |
data-kiln-gallery | a data-cms-repeat | A photo gallery: multi-upload, captions, thumbnail grid, visitor lightbox. Thumbnail size via data-kiln-thumb="120|180|260". |
data-kiln-events | a data-cms-repeat | An events list: structured event form for editors, list + month/week/day calendar for visitors. |
Everything else (tags/filters, documents, members areas, blog templates) is covered in KILN_PROMPT.md, written so you can hand it to an AI along with your repo.
Troubleshooting
Quick answers to the common ones.
- "Publishing…" for a while — your host is rebuilding. Kiln keeps checking; the change is committed and will appear.
- A new image looks broken after publishing — the deploy hasn't finished; Kiln swaps in the real image when it's live.
- Sent back to the sign-in screen — your session expired (or your access changed). Sign in again at
/kiln. - "You're not on the list (yet)" — the owner needs to add your exact Google email under People & access.
- Made a mess? History → Go back to this on the last good version — preview it on the page, keep it, publish. Every publish is kept forever.
- Self-host health check —
npx github:kilncms/kiln doctorverifies the worker, app, config, and annotations end to end. - Something else? Open an issue or email [email protected].