Configuration reference

The site is configured by a single plasmoid.toml at the docs root. Every field has a sensible default, so a minimal config is just a title:

[site]
title = "My Project"

Unknown keys are rejected, so a typo is caught at build time rather than silently ignored.

`[site]`

[site]
title = "My Project"            # required
default_locale = "en"           # default: "en"
locales = ["en", "es"]          # default: ["en"]; must contain default_locale
repo_url = "https://gitlab.com/you/project"   # optional, enables the chrome "Source" link
logo = "brand/logo.svg"         # optional, path relative to the docs root

Key	Default	Notes
`title`	—	Required, non-empty. Shown in the chrome.
`default_locale`	`"en"`	Defines site structure and the fallback locale.
`locales`	`["en"]`	All published locales. Must include `default_locale`.
`repo_url`	none	Optional repository URL. Enables the chrome “Source” link. Leave unset to omit it.
`logo`	none	Image (relative to docs root) shown in the chrome.

`[versions]`

[versions]
source = "cargo"   # "cargo" | "manual"; default "cargo"
retain = 5         # newest N kept live; default 5, must be ≥ 1

source = "cargo" reads package.version from the Cargo.toml above the docs dir. source = "manual" requires --version on every build.
retain controls how many versions stay live before older ones are zip-archived. See Versioning.

`[landing]`

[landing]
dir = "landing"    # optional: a prebuilt static landing to mount at /

If dir points at a directory, plasmoid copies it to / verbatim. Otherwise the markdown home (or a redirect) is used — see Deploy overview. Whenever a real landing sits at /, the docs chrome’s brand/logo links back to it automatically; point the landing’s “Read the docs” link at the stable /docs/ alias to close the loop.

`[theme]`

[theme]
palette = "default"                   # tone to emit — default
themes_dir = "../brand"               # external theme library (optional)
font_body = "Atkinson Hyperlegible"   # default (bundled, OFL)
font_mono = "JetBrains Mono"          # default
fonts = "self-hosted"                 # "self-hosted" (default) | "system"

Key	Default	Notes
`palette`	`"default"`	Tone to emit; the emitted `/assets/tokens.css` is the shared base layer + this tone. The binary ships only the neutral `"default"`; any other name is resolved from `docs/themes/<name>.css` or `themes_dir`. Overridden by `--palette`. See Theming.
`themes_dir`	(unset)	External theme library dir holding `tokens.base.css` + `themes/<tone>.css` (same layout as `docs/`). Lets a project use named tones without bundling them into the binary. A relative path resolves against the docs dir. Overridden by `--themes-dir`.
`font_body`	`"Atkinson Hyperlegible"`	Body family. The bundled default self-hosts automatically.
`font_mono`	`"JetBrains Mono"`	Monospace family (system fallback unless you supply a `mono*` woff2).
`fonts`	`"self-hosted"`	`"self-hosted"` emits `@font-face` (bundled default or `docs/fonts/*.woff2`); `"system"` uses the system stack only.

See Theming for choosing a tone and self-hosting your own woff2.

`[deploy]`

[deploy]
aliases = "symlink"   # "symlink" (default) | "copy" | "redirect"

How the stable /docs/ + /latest/ aliases are materialized.

Complete example

[site]
title = "plasmoid"
default_locale = "en"
locales = ["en"]
repo_url = "https://gitlab.com/rglw/plasmoid"   # powers the "Source" link

[versions]
source = "cargo"
retain = 5

[landing]

[theme]
palette = "default"
font_body = "Atkinson Hyperlegible"
font_mono = "JetBrains Mono"
fonts = "self-hosted"

[deploy]
aliases = "symlink"