dropbits Documentation

Site directory layout

Each Dropbits site is a folder under dropbits/sites/<id>/. The kernel (src/, packs/, public/, bin/) is shared; site truth is SQLite + themes + uploads.

For where documentation lives in the monorepo (docs/ vs dropbits/docs/ vs website/), see Repo docs layout.

Typical tree

dropbits/
  sites.json                 # tracked — demo minimal only
  sites.local.json           # gitignored — private site ids
  sites/
    minimal/                 # shipped demo / smoke fixture
      themes/<slug>/
        shell.html           # or index.html
        dropbits-site.css    # site identity (scanner)
        dropbits-user.css    # LLM / user overrides only
      assets/cms/            # optional theme-classes.json, …
      data/
        site.db              # content DB (never routine-deploy upload)
        uploads/             # media files
        backups/             # SitePack / CLI backups
        llm-api.key          # optional server LLM key (gitignored)
        snapshots/           # checkpoint slots
    _template/
      deploy.env.example     # copy → sites/<id>/deploy.env
      README.md
    <id>/                    # private / production site on the host
      deploy.env             # gitignored — LOCAL_INSTALL_ROOT, …
      sites.production.json  # install registry (gitignored)
      themes/ …
      data/ …

What lives where

PathRole
themes/<active>/Shell + CSS layers (base / site / user) — see product CSS convention
data/site.dbPages, widgets, entities, grants — content-owned
data/uploads/Uploaded media — content-owned
assets/Optional site assets (e.g. curated class catalog)
deploy.envHost-local deploy targets (never commit secrets)

Registries

FileRole
sites.jsonTracked demo registry (minimal)
sites.local.jsonDev overlay for private ids (gitignored)
sites/<id>/sites.production.jsonInstall sites.json for a production tree

Do not add customer site trees to the public git registry.

New site (dev host)

mkdir -p dropbits/sites/<id>/{data,themes/default}
# copy shell/CSS from sites/minimal/themes/default as a start
cp dropbits/sites/_template/deploy.env.example dropbits/sites/<id>/deploy.env
# merge <id> into gitignored sites.local.json
DROPBITS_SITE=<id> ./bin/site migrate
DROPBITS_SITE=<id> ./bin/site seed-minimal

See also