Appearance
The files under jtk/
What a site's repository holds under jtk/, file by file, in the shape the platform reads and writes them. You can seed a repository before anybody opens the panel, and an import reads back exactly what you wrote. This is contract 3, the contract every new site is written in, and npx @jtakeit/astro create lays it out. A site made before 12 November 2026 may still be on contract 2. Its files are at the end, and nothing new is written that way.
jtk/
schema.json the schema: what the owner may edit — yours, written by `jtk schema`
pages/index.json a page, named for its address: `/` is index.json
pages/prices.json /prices
pages/prices.en.json its English, beside it — a translation
entries/services/manicure.json an entry of the collection `services`
entries/services/manicure.en.json its English
shared.json the text on every page: the contacts, a footer note
shared.en.json
modules/bookings.json the diary's settings, when the schema turns bookings on
site.json the platform's, to the site: its id, slug, media host, currency
design.json the template's own: the editor's chromeWhat every file keeps to
- The directory is the kind. A page is under
pages/, an entry underentries/<collection>/, a module's settings undermodules/. A file under any of them says what its place says. Apath,collectionorslugthat disagrees with the file's place is refused withJTK_E_DOCUMENT_INVALID. - One identity per thing, minted once. A page and an entry have an
id, a lowercase UUID (version 7 when new). A block, a row of a list and a picture of a gallery have a_key: a lowercase letter, then lowercase letters, digits and hyphens, up to 32. Nothing is named by its place in a list.npx @jtakeit/astro schema(jtkit schemaon another generator) mints every name a file lacks, and so do the platform's saves. A file written by hand without them is refused (JTK_E_UNNAMED,JTK_E_DOCUMENT_INVALID). - Empty is absent. Leave a value nobody wrote out of the file. Never write
null,""or[]; an import folds them away. - No key a document has not got. A key that is neither the file's own nor a field the schema declares is refused. Inside an object the reserved keys are
_keyand_orphans, and in a block alsotype,vandview; any other_key is refused. - Values are what their kinds say (field kinds). A price is
{"minor": 4500}, a picture{"src": …, "alt": …}, a reference the entry'sid. Contract 2's shapes — a bare number, a picture's key, a slug — are refused here. - One form. The platform writes a file as
JSON.stringify(value, null, 2)does, with one newline at the end. The top-level keys come in the order this page gives. In every object below them,_key,type,vandviewcome first, the rest in byte order, and_orphanslast. A file you wrote that says the same as the save would is kept byte for byte, so the form is the platform's habit, not your rule. - Whose each file is. The schema is yours.
site.jsonis the platform's. Pages, entries, the shared text and a module's settings are the owner's, through the three stages: you seed them,import_branchreads them into the panel, and every save writes them back as a commit. Records — enquiries, bookings, orders — are never in git.
A place in a file is named by keys in an annotation, data-jtk-path, and in a translation. The kit's door writes the annotations, so a template never spells one:
| place | named |
|---|---|
| a field of a block on the page | blocks[hero].title |
| a field of a row | blocks[faq].items[r7k2].answer |
| a part of a picture | blocks[hero].image.src, blocks[hero].image.alt |
| an entry's own value, on its own page | title |
| an entry's value where it is listed | entry:0193a5c3-…:title |
| another page's block | page:0193a5c2-…:blocks[hero].title |
| the shared text | shared:blocks[contacts].phone |
| a module's setting | module:bookings:hours[mon].opens |
schema.json — the schema
The site's declaration of what its content is made of: the schema format. On the scaffold, npx @jtakeit/astro schema writes it from src/content/blocks.ts, which says CONTRACT = 3. On another generator you write it by hand or with your own tool. The platform reads it and never writes it.
pages/<path>.json — a page
A page at its address: / is pages/index.json, /prices is pages/prices.json, and /team/anna is pages/team/anna.json. The keys come in this order:
json
{
"id": "0193a5c2-7f4e-7c1a-9b2e-5d1f0c3a8e21",
"path": "/prices",
"name": "Preise",
"seo": { "description": "Was ein Termin bei uns kostet.", "title": "Preise" },
"blocks": [
{
"_key": "hero",
"type": "hero",
"v": 1,
"image": { "alt": "Der Salon am Morgen", "focus": "50% 30%", "src": "media/2f0c…/a1b2c3d4.jpg" },
"title": "Preise"
},
{
"_key": "list",
"type": "priced_list",
"v": 1,
"items": [
{ "_key": "r7k2", "price": { "from": true, "minor": 4500 }, "title": "Haarschnitt" }
]
}
]
}idis the page's own and never changes. An import knows a file by it, so a file moved or renamed in git is the same page at its new address, with its history. When the version at the new address goes live, the platform sends the old address on to it (301), so no redirect of your own is needed. A new file may carry a fresh UUID;jtk schemamints one where there is none.pathis the address, and it agrees with the file's place.nameis what the panel calls the page — Preise, Team, Kontakt — in the site's own language. It is required, and a page without one is refused. Visitors never see it, and the owner may rename it.seoholds the fields the schema'spage_seodeclares. Leave it out for none.blocksare the page in order. Each block carries its_key, itstype, its type'sv,viewif its type has views, and then its fields' values. A block at an oldervis brought up by its type'supcaststeps when it is read, and the next save writes the current one — upcasters.
A block may also carry _orphans: the values of fields the schema no longer declares, kept so that a field renamed or removed in the schema loses nothing. A page draws nothing from it. Leave it where it is, and delete a key from it only to drop that value on purpose.
entries/<collection>/<slug>.json — an entry
An entry of a collection: its directory is its collection and its file name is its slug. Its address is the collection's route with the slug in it, so /services/manicure for {"detail": "/services/{slug}"}. An entry of a collection with route: "none" has no page and no address. It is shown where shown_on says, /prices#manicure, and read by the diary.
json
{
"id": "0193a5c3-0a11-7d02-9f3c-1e2d3c4b5a71",
"collection": "services",
"slug": "manicure",
"rank": "a0",
"visible": true,
"fields": {
"costs": { "minor": 4500 },
"takes": 60,
"title": "Manicure"
}
}The keys come in this order: id, collection, slug, rank, visible, show_at, hide_at, seo, fields and blocks.
fieldsholds the entry's own values, the fields of its collection's type. They are annotated on its own page by their keys alone (title), and wherever the entry is listed asentry:<id>:title. Because the values sit underfields, a field may take any name,collectionandslugincluded.blocksis the entry's body, of the block types the collection'sblocksallows: a post's paragraphs and pictures. Leave it out for an entry with none.rankis the entry's place in a collection ordered by hand, which is the default: a short key compared as bytes (a0<a0V<a1). The owner's moves in the panel write it. Read it and do not renumber it; an entry without one comes after the ranked ones. A collection ordered by a field has norank.visibleis always written: whether the owner shows the entry. An entry the owner takes off the site or puts back in the panel is built as they said from the next build on, and the next save writes the samevisibleinto the file. An entry with a page of its own that the owner hides or deletes in the panel may send its address somewhere — its listing by default — and the platform redirects it, as it does an address an entry moved from; the owner sees and changes these in the panel (the panel). Write no redirect of your own for them.show_atandhide_atare moments in RFC 3339 and UTC —"2026-12-01T00:00:00Z"— for an entry meant to appear later or to go on a date. Outside its window the entry is treated as hidden: it is off the listing, the feed, the sitemap and the diary, and the edge answers a visitor 404 at its address while the people editing the site still see it. The platform builds the saved commit a few minutes ahead of the moment and points the site at it when the moment comes. Ahide_atnot after theshow_atis refused. On a collection whose entries are over by their date (ends_by, the schema) write the date, never a moment: the platform works out when each is over, and withthen: hideitshide_attoo. Never compare the date with today in the template — readended.seois only for an entry with a page of its own, and it holds the same fields as a page's.
A body field is markdown inside the JSON, never a .md file. Entries were markdown with frontmatter once, and an import refuses that shape by name.
An entry of a collection a module books — a service, a master, a car — is in every language, always (translations).
shared.json — the text on every page
One document, with no id and no address: the blocks of the types the schema's shared lists, usually one contacts block whose fields say their role. The structured data a search engine reads is built from those roles. A shared field is annotated wherever it is drawn as shared:blocks[contacts].phone.
json
{
"blocks": [
{
"_key": "contacts",
"type": "contacts",
"v": 1,
"city": "Winterthur",
"email": "praxis@example.ch",
"name": "Orthopädie Bischofsberg",
"phone": "+41 52 350 91 25",
"postal_code": "8400",
"street": "St. Georgenstrasse 6"
}
]
}modules/<module>.json — a module's settings
The module's own document: v, the version of its settings, and settings, whose keys the modules reference lists. Every row of a list in it has its _key. Seed it in the commit. npx @jtakeit/astro schema writes an empty one when the schema turns the module on. import_branch reads it into the diary, so the preview takes bookings before anybody opens the panel. The owner changes it under the diary afterwards, and the next save writes it back.
json
{
"v": 1,
"settings": {
"cancel_until": 1440,
"closed": [
{ "_key": "xmas", "from": "2026-12-24", "until": "2027-01-03" }
],
"confirm": "auto",
"hold": 1440,
"horizon": 60,
"hours": [
{ "_key": "mon", "closes": 1080, "day": "monday", "opens": 540 },
{ "_key": "tue", "closes": 1080, "day": "tuesday", "opens": 540 },
{ "_key": "fri", "closes": 1020, "day": "friday", "opens": 540 }
],
"lead": 120,
"page": "/book",
"party": 1,
"payment": "no",
"slot_every": 30,
"zone": "Europe/Zurich"
}
}Times of day are minutes from midnight (540 is 09:00), durations are whole minutes, and money is {"minor": …}. A closing time before the opening one is after midnight, so a bar's Friday of 18:00–01:00 is one row. deposit is a share of the price, 1–100, and belongs only beside "payment": "deposit". A zero is refused, so leave it out when nothing is paid up front. Anything beside v and settings, or a value a setting's kind refuses, is refused with JTK_E_DOCUMENT_INVALID. CI judges this example with the same judge import_branch applies, so it cannot go stale.
<name>.<locale>.json — a translation
A page, an entry, the shared text or a module's settings in another of the site's languages is a file beside its original: pages/prices.en.json, entries/services/manicure.en.json, shared.en.json. It holds only the words, named by the original's keys. A value that is the same in every language is never in it. Translations has the file, which values belong in it, and how the platform tells what is missing and what is outdated.
site.json — the platform's file
The platform writes it on every save: the site's id, its slug, where the owner's uploads are served from, and its currency. Do not seed id. An import reads back only currency, and only while the site has none, as create_site takes it. Once the site has a currency, a person changes it in the panel (The site → The business). An import or a validate_schema that brings another currency is refused with JTK_E_CURRENCY_SET. The business's name, address and phone are not here. They are content, in shared.json.
json
{
"id": "05d84518-b91f-44be-85a4-e2cb1ed11a13",
"slug": "orthopaedie-bischofsberg",
"media_base": "https://media.jtakeit.com/",
"currency": "CHF"
}design.json, and dist/_meta.json
design.json is the template's own file, not the contract's: the editor's chrome (the field, the ground, the accent). The scaffold ships an empty one that the panel fills.
dist/_meta.json is written by the site's build, not committed under jtk/. It says redirects ([{"from": "/old", "to": "/new", "status": 301}]), immutable (the directories whose files are named by their contents) and cache ([{"prefix": "/clips/", "maxAge": 86400}]), and nothing else. Which entries a visitor may not see is the platform's to say, so contract 3 has no drafts. Anything else is refused with JTK_E_META_INVALID.
Contract 2, the older contract
A site made before contract 3, and not yet moved, keeps these files. The platform's team moves such a site with jtk upgrade contract-3, in one commit. Never start a site in them. A tree that holds both jtk/schema.json and jtk/catalogue.json is refused.
jtk/
catalogue.json the schema, "contract": 2 — written by `jtk catalogue`
content/index.json a page, {id, path, name, seo, blocks}
content/de/prices.json a page in another language: a full copy at /de/prices
content/services/manicure.json an entry under its collection's prefix
shared.json, shared.de.json the text on every page
bookings.json the diary's settings, one bookings_config block
site.json the platform's, with the business's facts under `business`On contract 2, an entry is {path, collection, visible, seo, blocks}, and its own values are the fields of blocks[0]. A file under a collection's prefix without collection is refused with JTK_E_ENTRY_NO_COLLECTION. Values take contract 2's shapes: a price as a bare number of minor units, a picture as its key with its description in a sibling <key>_alt field, and a reference as a slug. A place is named by position, blocks[0].title.
bookings.json, contract 2
One block of type bookings_config, whose fields are the same settings, in the shape a save writes. Anything else is refused with JTK_E_MODULE_FILE_INVALID.
json
{
"blocks": [
{
"type": "bookings_config",
"v": 1,
"zone": "Europe/Zurich",
"slot_every": 30,
"confirm": "auto",
"payment": "no",
"hours": [
{ "day": "monday", "opens": 540, "closes": 1080 }
]
}
]
}