Config reference

Every build writes site.json next to the pages. It holds the whole plan for the site: the words, the theme, the nav, and the footer. Edit it in any text editor and rebuild with build --from at zero tokens.

Top-level fields

These are the fields of site.json in version 0.1.0, with the limits the engine applies when it reads the file.

meta

title, description, and lang. The description is cut to 155 characters, and lang defaults to en.

theme

template, dark, accent, and accent2.

nav

Up to 7 links, each with a label and an href.

pages

Up to 5 pages with up to 12 sections each. The first page is always index.

footer

text, up to 6 links, and credit, which is true or false.

citations

The copy file behind each section. The renderer ignores it, and rebuilds and the checker read it.

presentation

The frame and mold ids, and the section slots they ask for.

version and generator

Version 0.1.0 writes version 1 and generator spidercaster/0.1, next to the brief text.

Theme values

Four values set the look. The same choices are flags on the build command.

template

modern, editorial, or bold. Any other value falls back to modern.

dark

true or false. A build is dark unless you choose light.

accent and accent2

A six-digit hex colour such as #a3e635, or null for the template colour.

From the command line

--template, --dark, and --light set the same values when you build.

Plan before you build

A dry run prints the plan for the site at zero tokens and writes nothing. The sections command lists every type and its fields.

build output
$ python spidercaster.py build projects/my-site --offline --dry-run
dry-run /tmp/spidercaster-docs-run/spidercaster/sites/corner-bike-fix: 0 tokens spent
--- /tmp/spidercaster-docs-run/spidercaster/sites/corner-bike-fix (current)
+++ /tmp/spidercaster-docs-run/spidercaster/sites/corner-bike-fix (planned)
@@ -0,0 +1,20 @@
+meta title="Corner Bike Fix"
+theme {"accent": null, "dark": true, "template": "modern"}
+page slug="index" title="Corner Bike Fix"
+  hero:hero
+    bullets=[]
+    eyebrow=""
+    headline="Corner Bike Fix"
+    image=""
+    image_alt=""
+    primary={"href": "#features", "label": "What we fix"}
+    secondary=null
+    subhead="Flat tyres, slipping gears and squeaky brakes, fixed while you wait or by the end of the day."
+  features:features
+    items=[{"body": "Tube or tyre swapped while you wait.", "icon": "sparkles", "title": "Flat tyres"}, {"body": "Cables tuned so every gear clicks in.", "icon": "sparkles", "title": "Gears"}, {"body": "Pads and cables set so the bike stops straight.", "icon": "sparkles", "title": "Brakes"}]
+    subhead=""
+    title="What we fix"
+  faq:faq
+    items=[{"a": "No. Walk in during opening hours.", "q": "Do I need to book?"}, {"a": "No. We only repair them.", "q": "Do you sell bikes?"}]
+    subhead=""
+    title="Questions"
  (sitemap stage diff lands with lib/sitemap.py; IR layer above)

Exit code: 0

sections output
$ python spidercaster.py sections
section types (data fields):
  hero         eyebrow, headline, subhead, primary{label,href}, secondary{label,href}, bullets[str]
  features     title, items[{icon,title,body}] (max 8)
  stats        items[{value,label}] (max 6)
  steps        title, items[{title,body}] (max 6)
  gallery      title, items[{label,caption,src,alt}] (max 12; src only for real local assets)
  pricing      title, items[{name,price,period,blurb,features[str],featured,badge,cta}] (max 4)
  testimonials items[{quote,name,role}] (max 6)
  faq          title, items[{q,a}] (max 8)
  cta          title, body, primary{label,href}
  contact      title, body, email, phone, address, hours
  about        title, body[str], points[{title,body}]
  team         title, items[{name,role,bio}] (max 8)
  menu         title, groups[{name,items[{name,desc,price}]}]
  logocloud    title, items[str] (max 8)

Exit code: 0

Section types for words

Each section has an id, a type, and data. The sections command prints every type with its fields.

hero

eyebrow, headline, subhead, a primary and a secondary link, and bullets.

about

title, body paragraphs, and points with a title and body.

features

title and up to 8 items, each with an icon, title, and body.

steps

title and up to 6 items, each with a title and body.

stats

up to 6 items, each with a value and a label.

faq

title and up to 8 items, each with a question and an answer.

cta

title, body, and one primary link.

More section types

The other seven types cover offers, people, places, and pictures.

pricing

title and up to 4 plans with name, price, period, blurb, features, featured, badge, and a link.

menu

title and groups of items, each with a name, description, and price.

gallery

title and up to 12 items with label, caption, src, and alt. src must be a real local file.

testimonials

up to 6 items with quote, name, and role, taken from your copy only.

team

title and up to 8 people with name, role, and bio.

contact

title, body, email, phone, address, and hours.

logocloud

title and up to 8 names.

Edit and rebuild

A rebuild from site.json makes no AI calls and costs zero tokens, so you can change words or colours as often as you like.

Open it

The site.json beside your pages is the plan for that build.

Change it

Edit words, colours, or links, and keep the JSON valid.

Rebuild

python spidercaster.py build --from sites/my-site/site.json --out sites/my-site

Quick theme flips

python spidercaster.py refine sites/my-site light --offline changes the theme only. It reads template names, light or dark, and a hex colour.