KilnKiln

Documentation

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

The fast way is one command. Run 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.

Starting from nothing, or leaving a builder

  • npx github:kilncms/kiln new [dir] — scaffold a fresh site from a template repo (--from owner/repo), de-personalized, git-initialized, wizard-ready.
  • npx github:kilncms/kiln rescue <url> — crawl a Squarespace, Wix, or WordPress site into a clean, self-contained static copy (assets localized, builder runtime stripped, lazy images fixed) and auto-tag it for Kiln.

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.
Caveat: Vercel's free Hobby tier prohibits commercial use — for business sites prefer Cloudflare Pages or GitHub Pages.

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 deploy

Note 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

  1. Open https://YOUR-WORKER.workers.dev/setup and 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.
  2. Click Install, choose Only select repositories, and pick your site's repo. Kiln can only ever touch repos you select.
  3. Add your site's URL to ALLOWED_ORIGINS in worker/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_SECRET

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

Pointing an AI at it instead? Give Claude, Cursor, or any agent your repo plus KILN_PROMPT.md — it can run these steps with your credentials and always handles the annotation.

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.

The one difference from self-host: on Kiln Cloud the GitHub App is our shared 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.

Source mode

For sites built with a generator. The pages are generated from content files — you edit the page, Kiln saves the underlying content and the site rebuilds.

Everything else in these docs assumes the HTML in your repository is the page. On a generator-built site (Astro, for now) it isn't: the repo holds markdown content files and the pages are built from them, so editing the generated HTML would be erased on the next build. In source mode Kiln edits the content files instead. Editors still click the text on the live page and type — which file the value lives in is Kiln's problem, not theirs.

It exists for the classic handoff: a developer builds an Astro site and hands it to someone non-technical who then needs to change a date. That person gets the same editor as everywhere else in these docs — sign in with Google, click, type, Publish. No markdown, no repo, no GitHub account.

New: shipped for self-hosted sites today; Kiln Cloud sites get it with this week's update. Astro first — Eleventy, Hugo and Jekyll follow.

Quickstart: the wizard asks

Run npx github:kilncms/kiln in the site's repo — the same wizard as the self-hosted install. It detects the generator from your files, shows what it found ("Found astro.config.mjs and 63 content files"), and asks how the site is built, in plain language:

  • The pages are files in the repository. You edit the page, Kiln saves the page.
  • The pages are generated from content files. You edit the page, Kiln saves the underlying content and the site rebuilds. Takes about a minute.

Pick the second and the wizard writes mode: 'source' into your Kiln config, deploys a worker that can commit to content files, and prints the remaining steps (annotate your components, verify the host auto-deploys, check the build's Node version). Already running Kiln self-hosted? npx github:kilncms/kiln update plus a redeploy of your worker brings an existing install up to date, and npx github:kilncms/kiln doctor verifies both.

One line per field

A generated page has to say which content file and field each value came from. In Astro that's the @kilncms/astro helpers, spread onto the elements your components render — one line per field, the same mental model as annotating a hand-written page with data-cms:

<h3 {...kilnSource(entry, 'title')}>{entry.data.title}</h3>
<time {...kilnSource(entry, 'date', { type: 'date' })}>{entry.data.date}</time>
<div {...kilnBody(entry)}><Content /></div>

Each helper stamps a data-kiln-source attribute naming the file and field (like src/content/events/service.md#/frontmatter/title), and signed-in editors see those elements outlined and editable like any other. The helpers live in the Kiln repo and are used from there for now — the wizard prints the steps, and the @kilncms/astro package comes to npm this week.

Publishing takes a build

In HTML mode a publish is live about a minute after the commit. In source mode your host has to rebuild the site first, so Kiln tells the truth about where a change is: Saved → Building… → Published ✓, driven by your host's real build and deployment status. If the build fails you see Build failed ✕ with what happened and a one-click Undo this change per committed file; the live site stays on its last good version in the meantime, so a bad edit never half-publishes. Edits on one page are grouped by content file and committed one file at a time ("Saving 3 changes across 2 content files").

What keeps it safe

  • Edits never touch code. Kiln writes markdown content files only — never .astro, .ts, .js, config, or templates, no matter who asks. Editable: .md frontmatter and body, and .mdx frontmatter (MDX bodies are code).
  • Invalid values are rejected with plain errors. Typed fields (date, time, URL, number, true/false) are checked on the worker before anything is committed — "This needs to be a date, like 2026-09-20", not a failed build.
  • Your files round-trip byte-identical. Frontmatter is spliced surgically, so comments, quoting, and key order in a content file survive an edit untouched.
  • Every change is still a Git commit — one per content file, attributed to the editor, in your history and revertible like everything else in Kiln.
  • The wrong-mode guard. A generator-built repo left in HTML mode with committed build output is blocked from editing that output, with an explanation — the alternative is an edit that silently vanishes on the next build, and Kiln refuses to be that.

Not yet, and we are honest about that: date-picker-style controls (typed values are validated but edited as text), Eleventy, Hugo and Jekyll adapters, and suggest-mode or scheduled source edits.

Signing in & out

There is no edit button on the site. To edit, go to yoursite.com/kiln.

Site owner

Choose Continue with GitHub. You get every capability on this page.

Invited editor

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. On a phone the editor reshapes into bottom sheets with thumb-sized targets and a keyboard-aware toolbar; desktop is unchanged.

The Kiln menu: Publish with one pending edit, drafts, scheduling, history, add gallery, make editable, site menu, find and replace, people and access, settings

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. Publish status is deploy-aware: Live ✓ — view site when your host’s deployment actually landed (with a content-probe confirmation), or Build failed — open commit when it didn’t. 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.

The text toolbar: style menu, bold, italic, underline, lists, link, image, document, clear, section history, Done, Revert
  • 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.

The image toolbar: Replace image, drag-the-corner-to-resize hint, and the alt text field
  • 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.

The Gallery options dialog: small, medium, or large thumbnails
  • + 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.

Comments & reviewers

Figma-style review on the live page.

💬 Comments pins a comment to any element. Threads keep who said what; you can resolve or reopen them. Each page has a sidebar and an open-count badge. A Reviewer preset in People & access creates a true comment-only seat — they can talk about the page and they cannot change it.

Suggest mode

Editors propose; you approve. Enforced on the worker, not just in the browser.

Tick Suggest-only publishing on an editor and their Publish becomes Suggest changes. Field-level suggestions land in an admin review queue with a per-field before/after. Approve re-applies onto the current page (conflict-safe; the suggester keeps authorship) or Decline throws it out. Suggest-mode sessions cannot write to the live branch, schedule, or bypass via the proxy.

⌘K palette

Jump, or search the site’s own text.

Press ⌘K (Ctrl+K on Windows) to jump to any page, field, or tool. The same palette searches the site with in-context snippets, scoped to what an invited editor is allowed to see.

Block library

Editors compose pages only from approved, brand-safe sections.

+ Add section sits between sections and is fed by _blocks/*.html snippets you (or an AI) author in the repo. Sections with a repeat key get a ✕ remove. Nothing here is a freeform page builder — if it is not in the library, it is not on the page.

Theme

The site’s :root CSS variables are the brand kit. No schema.

The Theme panel turns those custom properties into color pickers, font menus, and size inputs, with a live preview. Saving writes a byte-exact stylesheet commit. The CSS is the source of truth.

On a phone

Same editor, reshaped for thumbs.

On a phone the editor becomes bottom sheets with thumb-sized targets and a keyboard-aware toolbar. Desktop is unchanged. Update your hours from the parking lot.

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.
  • One preview config line turns drafts and suggestions into real, shareable branch-preview URLs built by your host. See Configuration.

History & rolling back

Every publish is a saved version. Name one if you like. Undoing always previews first — nothing goes live until you Publish.

You can name any publish (git tags under kiln/) so “summer menu” is easier to find than a hash. 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, every restore now shows a sandboxed side-by-side “Now vs. this version” preview before anything is staged. Keep it and it stages 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, reviewers, 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. Tick Suggest-only publishing and their Publish becomes Suggest changes — see Suggest mode.
  • Reviewer — a comment-only seat (mode: review). They pin comments on the live page; the worker refuses every write for those sessions.
  • 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, comments, AI assist, blocks, theme, 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:

Editable / plain text

Click-to-edit, with or without formatting.

Swappable image

Click to replace, resize, set alt text.

Repeating blocks

Add / reorder / remove / tag the items inside.

Menu

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. Approved brand sections from your _blocks/ library are added with + Add section — see Block library.

The Add a section dialog: Photo gallery or Events list

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.

AI assist

Optional. Bring your own API key. Kiln does not sell a hosted AI plan.

Improve / Shorten / Tone / Translate / Custom on any field, with a before/after preview; one-tap alt text for images; and “draft the content” on new posts. It goes through a /ai/assist worker endpoint. Self-host: wrangler secret put AI_API_KEY. Same sanitizer and commit pipeline as a human edit, and you grant it per editor.

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
};
KeyRequiredWhat it does
repoyesThe GitHub repository (owner/name) Kiln reads from and commits to.
branchnoBranch to commit to. Default main.
workeryesURL of the sign-in worker. Self-host: your workers.dev URL. Kiln Cloud / managed: ours (set for you by the prep command).
stylesnoArray of {label, class} entries exposed in the text toolbar's Style menu, so editors can only apply on-brand styles.
rootnoSubfolder of the repo the site is served from, if not the repo root.
homenoPath of the homepage file if it isn't index.html.
siteNamenoDisplay name shown on the /kiln sign-in screen.
entrynoSet false to disable the /kiln entry page handling, or a string path (e.g. '/edit') to use a custom entry path instead of /kiln.
authnoSign-in options. auth: { google: false } hides the Continue with Google button on the sign-in screen.
previewnoOne line like preview: 'https://{branch}.yourproject.pages.dev' turns drafts and suggestions into shareable branch-preview URLs from your host.

Annotation reference

Plain HTML attributes mark what's editable. Your AI (or the wizard) usually writes these.

AttributeOnMakes it
data-cms="key"any text elementClick-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-plaina data-cms elementPlain 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 containerRepeating blocks — every child becomes add/duplicate/reorder/remove/tag-able. Works on lists, card grids, and table sections.
data-cms-menu="key"your navThe managed site menu, editable once and synced across every page.
data-kiln-gallerya data-cms-repeatA photo gallery: multi-upload, captions, thumbnail grid, visitor lightbox. Thumbnail size via data-kiln-thumb="120|180|260".
data-kiln-eventsa data-cms-repeatAn 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.

REST API & kiln-mcp

The page is the schema. Shipped in v0.4.0.

Three endpoints on the same worker the editor already uses, behind an owner-minted Bearer token scoped by path, section keys, read-only, and expiry:

  • GET /api/v1/pages — pages this token may see
  • GET /api/v1/fields?path=/ — that page’s editable fields as JSON
  • PATCH /api/v1/edits — { path, edits, message? } where each edit is {key, html} or {key, attr, value}. One sanitized, attributed commit.

On Kiln Cloud the worker is https://auth.kilncms.com. Self-host, it is yours. kiln-mcp is an MCP server over that API: list pages, read fields, apply edits. Setup is in the kiln-mcp README, and the marketing page is API.

Troubleshooting

Quick answers to the common ones.

  • "Publishing…" for a while — your host is rebuilding. Kiln keeps checking and will flip to Live ✓ or Build failed; the change is already a commit.
  • 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 doctor verifies the worker, app, config, and annotations end to end.
  • Something else? Open an issue or email [email protected].