# Configuration reference

Source: https://twiki.twango.dev/reference/configuration

# Configuration reference

<!-- Generated by bun run docs:generate. Edit the source definitions, not this page. -->

Generated from [the runtime schema](https://github.com/twangodev/twiki/blob/main/site/tooling/lib/project-schema.ts). The same schema validates configuration and provides TypeScript types.

For editor completion, add `"$schema": "./node_modules/@twango/twiki/cli/twiki.schema.json"` to a root-level `twiki.config.json`. Adjust the path if your config lives elsewhere. The package also exports `@twango/twiki/schema`.

| Field | Type / values | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `$schema` | string | No | — | Optional JSON Schema URL or local path for editor completion. |
| `version` | `1` | Yes, when parent exists | — | Configuration format version. |
| `contentDir` | string | No | — | Content directory relative to the vault root. Explicit CLI projects default to the current directory. |
| `discovery` | `filesystem`, `git` | No | — | File discovery. Explicit CLI projects default to filesystem; legacy workspaces default to git. |
| `publication` | `private`, `public`, `policies` | No | — | Publication mode. Explicit CLI projects default to private. Static export requires public. |
| `site` | object | No | — | Branding, canonical URL, author and navigation settings. |
| `site.name` | string | No | `"twiki"` | Site name shown in navigation. |
| `site.title` | string | No | `"twiki"` | Default page title. |
| `site.url` | string | No | `"http://localhost:5173"` | Canonical HTTP or HTTPS origin. |
| `site.description` | string | No | `"Notes, ideas, and reference material."` | Default site description. |
| `site.author` | object | No | — |  |
| `site.author.name` | string | No | `""` |  |
| `site.author.url` | string | No | `""` |  |
| `site.author.github` | string | No | `""` |  |
| `site.author.email` | string | No | `""` |  |
| `site.locale` | string | No | `"en_US"` | Open Graph locale. |
| `site.language` | string | No | `"en"` | HTML language. |
| `site.navigation` | object | No | — |  |
| `site.navigation.mode` | `courses`, `sections` | No | `"courses"` | Course navigation or general documentation sections. |
| `site.navigation.workspace` | string | No | `"Workspace"` | Navigation switcher caption. |
| `site.navigation.browse` | string | No | `"Browse courses"` | Navigation switcher label. |
| `site.navigation.find` | string | No | `"Find a course"` | Section search label. |
| `site.navigation.home` | string | No | `"Workspace home"` | Link to the vault home. |
| `site.navigation.all` | string | No | `"All courses"` | Unfiltered search label. |
| `cloudflare` | object | No | — | Wrangler resource settings. Twiki supplies generated main and assets paths. Never put credentials here. |
| `analytics` | object | No | — | Optional analytics site and endpoint. Disabled when omitted. |
| `analytics.siteId` | string | Yes, when parent exists | — |  |
| `analytics.scriptUrl` | string | No | — |  |
| `analytics.endpoint` | string | No | — |  |

Absent values preserve context-sensitive defaults: an explicit CLI vault uses filesystem discovery, the vault root as content directory, and private publication. Legacy engine workspaces use Git discovery, `content/` and publication policies. Schema defaults for site metadata match runtime branding defaults.

The `cloudflare` object passes resource settings to Wrangler; Twiki controls generated `main` and `assets`. Never store an API token here. See [[guides/cloudflare|Cloudflare deployment]], [[guides/authentication|Authentication]] and [[examples/public-vault|Public vault example]].