Theme kits and site files

Two ways to move a design or a whole site as files: a theme kit packs the look (tokens, headers, footers and templates, with their fonts and images) to reuse on another site, and a site folder keeps an entire site's pages, theme and parts as plain files you can keep in a repository.

Theme kits

A kit is a .ganseykit.tgz package holding theme.toml (name and format), tokens.json, one JSON file per site part under parts/, and the font files and library images those refer to under assets/.

Export the published theme from Theme → Tokens → Kits → "Export this theme", or:

gansey theme export oak-and-ash.ganseykit.tgz --name "Oak and ash"

The kit takes the published tokens and the published site parts that do not belong to a content type or taxonomy. Display rules that name pages are left out, since page ids mean nothing on another site; path rules are kept. A part that places a synced block carries a copy of the block's section instead, since the block itself stays behind.

The files the tokens and parts use go under assets/: those placed by media id (a font face, an image chosen from Media) and those placed by address, such as a picture in a header's rich text or an image's address (/media/...). The kit refers to those as assets/<file>, so they still show on the site the kit is installed on. A file a part shows whose library entry is gone is still carried from the media folder.

Install a kit from the same Kits tab, or:

gansey theme import oak-and-ash.ganseykit.tgz            # tokens as a revision, parts as drafts
gansey theme import oak-and-ash.ganseykit.tgz --publish  # publish them and make the parts the defaults

Installing uploads the assets into the media library (images get their sizes, as uploads do), points every reference at the new files, saves the tokens as a theme revision and creates each part as a draft. With --publish (or the tick box in the admin) the tokens and parts go live and the parts become the site defaults.

Site folders

gansey site export writes the published site into a folder, and gansey site import brings a folder into a site's database:

site.toml                       name, format, switched-off modules, asset ids, redirects
theme/tokens.json               the published theme tokens
theme/parts/*.json              headers, footers, page templates and content templates
blocks/*.json                   saved blocks
pages/*.json                    one file per page
content/types/*.json            content types
content/taxonomies/*.json       taxonomies with their terms
content/entries/<type>/*.json   one file per entry
assets/*                        images and fonts the documents and entries use

gansey site export sites/oak-and-ash
gansey site import sites/oak-and-ash             # changed documents arrive as drafts
gansey site import sites/oak-and-ash --publish   # and go live

A page file is named after its path (index.json for the home page, services--kitchens.json for /services/kitchens) and holds the page's metadata and its document:

{
  "slug": "services/kitchens",
  "title": "Kitchens",
  "status": "published",
  "description": "Fitted kitchens in solid oak and ash.",
  "nav_order": 2,
  "show_in_nav": true,
  "document": { "version": 1, "sections": [] }
}

Export writes every page that is not archived, with its published document (or its latest one for a page never published), every published part (content templates included), every saved block, archived ones included, every content type and taxonomy, and every entry that is not archived. It rewrites pages/, theme/parts/, blocks/ and content/ from scratch and writes the files the documents and entries use into assets/: those placed by media id, and those placed by address, such as a picture in rich text or an image's address (/media/...). Documents then refer to those files as assets/<file>, or by a media id listed under [assets] in site.toml. A file a page shows whose library entry is gone is still carried, as <id>.<ext>, from the media folder.

A block file keeps the block's id, because pages place synced blocks by id; import matches blocks by that id and creates any that are missing under it.

Content is matched by slug, never by id. A type file holds what the Content types screen does, with its taxonomies by slug; a taxonomy file holds its terms, each under its parent's slug. An entry file is named after the entry and sits in its type's folder:

{
  "slug": "oak-chair",
  "title": "Oak chair",
  "status": "published",
  "excerpt": "A chair for the long table.",
  "published_at": "2026-10-28T09:00:00Z",
  "featured_image": "8ad389a7-24e1-4a0e-af90-afa794e96a70",
  "terms": { "category": ["chairs"] },
  "fields": { "client": "Oak & Ash", "story": "<p>Made slowly.</p>" }
}

A content template names its type ("content_type": "projects") or taxonomy ("taxonomy": "category"). An entry's own page is not carried. Redirects are listed in site.toml:

[redirects]
"/work/oak-chair" = "/projects/oak-chair"

Import uploads each asset once and remembers it, rewrites the references to the uploaded files, and saves a new revision only for documents that changed, so importing the same folder twice does nothing the second time. A /media/... address the documents still use, whose file is in the site's media folder but missing from Media (a database rebuilt from the files beside an existing folder), is listed in Media again under its own id, so the address keeps working. Content types, taxonomies and terms are brought up to date on every import, their fields tidied as the Content types screen tidies them. Entries are records without drafts, so without --publish new entries arrive as drafts and existing ones are left alone. With --publish, changed pages marked published go live, parts become the defaults the files say they are, the tokens are published, entries take the values, terms and status in their files, and the module switches and redirects in site.toml are applied. Import adds and updates; a page, entry or redirect whose file or line you removed stays on the site until you delete it in the admin. A running server keeps its page cache, so restart it after an import.

Not in the files: users, media not used by the theme, a page or an entry, a page's parent and its own header and footer choice, and an entry's own page. Keep those in backups (see Running a site).

Pages only

gansey page export and gansey page import move just the pages, as one JSON file (or standard output and input with -):

gansey page export pages.json
gansey page import pages.json --publish

The export holds each page's path, title, status, description, navigation order and visibility, with its latest and its published document. Import updates pages at existing paths with a new revision and creates the rest; with --publish it publishes those that were published in the export. It carries no media files, so media ids in the documents only resolve on a site that already has those items; use a site folder to move images too.