dropbits Documentation

Repo docs layout

Where documentation lives in this monorepo — and what that means when you publish the dropbits/ tree (e.g. to Codeberg).

Paths

PathRole
Repo-root docs/Normative / development — SPEC companions, OPEN-DECISIONS, DEPLOY, TOOLBOX, publish-manifest.json, …
dropbits/docs/Public user + site-builder guides (Markdown sources; generated HTML + Pagefind are website build artifacts)
website/docsSymlink → ../dropbits/docs
website/Landing page + deploy scripts (docs:sync, docs:deploy)

Contributor truth stays at repo-root SPEC.md and docs/. Public guides under dropbits/docs/ are what dropbits.org /docs/ serves. Pagefind search is dropbits.org only (D35) — not part of the install tip.

Site-specific docs (binding)

Named dogfood / customer sites, host paths, public URLs, and per-site cutover notes never belong in tracked common documentation (dropbits/docs/, repo-root docs/ runbooks, root README). Put them under:

HomeWhat belongs there
deployable/<id>/ (usually a symlink to a private dogfood repo)Site README, DEPLOY.md, import notes, install paths
Private dogfood git (sibling of the monorepo)Same trees versioned; not Codeberg / not the kernel tip
docs/DOGFOOD-PORT.md (gitignored)Cross-site host inventory / cutover scratch for this machine
Playground tenant tree (when present)Notes for that tenant only — not the hub UI

Tracked docs use generic placeholders: <id>, example.com, blog, minimal, _smoke. Historical evidence in DECISIONS.md / closed OPEN-DECISIONS may still name a site; do not extend that pattern into runbooks or product guides. See AGENTS.md prohibition 14.

After editing guides (monorepo only)

If you have the full product monorepo (this page’s relative links to website/ and repo-root docs/ resolve), rebuild published HTML from the monorepo root:

npm run docs:sync     # MD → HTML + Pagefind under dropbits/docs/ (website)
npm run docs:deploy   # optional — sync then rsync website/ to dropbits.org

A Codeberg / runtime-only clone does not include website/, Pagefind, or that npm pipeline — use the guides as shipped Markdown (and HTML without search chrome), or read dropbits.org/docs.

Codeberg implication

The public tip / release zip is playground/ (hub) beside dropbits/ (kernel + these public guides as Markdown, and maybe generated HTML without Pagefind). Normative repo-root docs/ and the marketing website/ shell are not inside dropbits/ unless you push the whole monorepo. docs/pagefind/ is always omitted from the tip / zip (D35).

Prefer a clean public tip: playground/ + dropbits/ + LICENSE (+ a short root README: clone -b v9, php playground/bin/serve, php playground/bin/deploy <id>). Do not put monorepo docs:sync / website deploy steps in that root README. Keep Spec/OPEN-DECISIONS in the monorepo (or a separate contributor clone).

See also