Configuration

All configuration lives in oxidoc.toml at the project root.

`[project]`

Core project metadata.

oxidoc.tomltoml

[project]
name = "My Docs"
description = "Documentation for my project"
logo = "/assets/logo.svg"
favicon = "/assets/favicon.svg"
base_url = "https://example.com"
edit_url = "https://github.com/org/repo/blob/main"
edit_label = "Edit this page"
debug_islands = false

Field	Type	Default	Description
`name`	String	required	Project name shown in header and metadata
`description`	String	—	Site description for SEO and feeds
`logo`	String	—	Path to logo image (relative to assets)
`favicon`	String	—	Path to favicon (`.ico`, `.svg`, or `.png`)
`base_url`	String	—	Full base URL for sitemap, feeds, and canonical links
`edit_url`	String	—	Base URL for "edit this page" links (e.g. GitHub blob URL)
`edit_label`	String	`"View page source"`	Label for the edit/source link on each page
`debug_islands`	bool	`false`	Show debug outlines on Wasm island components

`[theme]`

Visual customization.

oxidoc.tomltoml

[theme]
primary = "#3b82f6"
accent = "#f59e0b"
font = "Inter, sans-serif"
code_font = "JetBrains Mono, monospace"
dark_mode = "system"
custom_css = ["assets/custom.css"]

Field	Type	Default	Description
`primary`	String	`"#2563eb"`	Primary color (links, buttons, active states)
`accent`	String	`"#f59e0b"`	Accent color for decorative elements
`font`	String	System font stack	Body text font family
`code_font`	String	Monospace stack	Code font family
`dark_mode`	String	`"system"`	Dark mode: `"system"`, `"light"`, or `"dark"`
`custom_css`	String[]	`[]`	Custom CSS files to load (paths relative to project root)

See Theming for the full CSS variable reference.

`[routing]`

Controls site structure, navigation, and sections.

`[routing.root]`

oxidoc.tomltoml

[routing.root]
homepage = "home.rdx"
pages = ["about.rdx", "contact.rdx"]

Field	Type	Default	Description
`homepage`	String	—	RDX file rendered at `/`
`pages`	String[]	`[]`	Additional root-level pages rendered at `/{name}`

`header_links`

oxidoc.tomltoml

[routing]
header_links = [
  { label = "Docs", href = "/docs" },
  { label = "GitHub", href = "https://github.com/org/repo" },
]

Field	Type	Description
`label`	String	Link text displayed in the header
`href`	String	URL (internal path or external URL)

`navigation`

Array of site sections. Each section has its own sidebar and content directory.

oxidoc.tomltoml

[routing]
navigation = [
  { path = "/docs", dir = "docs", groups = [
    { group = "Getting Started", pages = ["intro", "quickstart"] },
    { group = "Guides", pages = ["guides/styling"] },
  ] },
  { path = "/api", openapi = "./openapi.yaml" },
]

Field	Type	Description
`path`	String	Base URL path (e.g., `"/docs"`, `"/api"`)
`dir`	String	Content directory for `.rdx` files (relative to project root)
`groups`	Array	Sidebar groups, each with `group` (title) and `pages` (slug list)
`openapi`	String	Path to OpenAPI spec — auto-generates API reference pages

Sections are fully independent — each has its own sidebar. You can mix .rdx content sections with OpenAPI sections:

oxidoc.tomltoml

[routing]
navigation = [
  { path = "/docs", dir = "docs", groups = [
    { group = "Guides", pages = ["intro", "quickstart"] },
    { group = "Advanced", pages = ["plugins", "theming"] },
  ] },
  { path = "/api", openapi = "./openapi.yaml" },
  { path = "/internal", dir = "internal-docs", groups = [
    { group = "Team", pages = ["onboarding", "runbooks"] },
  ] },
]

Content directories

Each section's dir is resolved relative to the project root. You can have as many content directories as you need — they don't have to be called docs.

Pages can use subdirectories — "guides/styling" maps to docs/guides/styling.rdx.

`[search]`

oxidoc.tomltoml

[search]
provider = "oxidoc"
semantic = true
model_path = "./models/embedding.gguf"

Field	Type	Default	Description
`provider`	String	`"oxidoc"`	Search provider: `"oxidoc"`, `"algolia"`, `"typesense"`, `"meilisearch"`, `"custom"`
`semantic`	bool	`false`	Enable semantic (hybrid) search alongside BM25
`model_path`	String	—	Path to custom GGUF embedding model

Provider-specific fields — see Search for details:

Provider	Fields
Algolia	`app_id`, `api_key`, `index_name`
Typesense	`host`, `port`, `protocol`, `api_key`, `collection_name`
Meilisearch	`host`, `api_key`, `index_name`
Custom	`stylesheet`, `script`, `init_script`

`[versioning]`

oxidoc.tomltoml

[versioning]
default = "v2.0"
versions = ["v1.0", "v2.0"]

Field	Type	Default	Description
`default`	String	—	Default version served at the root URL
`versions`	String[]	`[]`	All available versions

See Versioning for the full guide.

`[i18n]`

oxidoc.tomltoml

[i18n]
default_locale = "en"
locales = ["en", "ja", "es"]
translation_dir = "i18n"

Field	Type	Default	Description
`default_locale`	String	`"en"`	Default locale (served at root, no prefix)
`locales`	String[]	`[]`	All configured locales
`translation_dir`	String	`"i18n"`	Directory for Fluent `.ftl` translation files

See i18n for the full guide.

`[footer]`

oxidoc.tomltoml

[footer]
copyright_owner = "My Company"
copyright_owner_url = "https://example.com"
links = [
  { label = "Privacy", href = "/privacy" },
  { label = "Terms", href = "/terms" },
]

Field	Type	Default	Description
`copyright_owner`	String	—	Name shown in copyright notice
`copyright_owner_url`	String	—	URL for the copyright owner name
`links`	Array	`[]`	Footer links, each with `label` and `href`

`[social]`

oxidoc.tomltoml

[social]
github = "https://github.com/org/repo"
discord = "https://discord.gg/invite"

Social links displayed in the header/footer.

`[analytics]`

oxidoc.tomltoml

[analytics]
google_analytics = "G-XXXXXXXXXX"
# Or inject a custom script:
# script = '<script defer data-domain="example.com" src="https://plausible.io/js/script.js"></script>'

Field	Type	Default	Description
`google_analytics`	String	—	Google Analytics measurement ID
`script`	String	—	Custom analytics script tag (injected in `<head>`)

See Analytics for details.

`[redirects]`

oxidoc.tomltoml

[redirects]
redirects = [
  { from = "/old-page", to = "/new-page" },
  { from = "/guide", to = "/docs/quickstart" },
]

Each entry generates an HTML file at from that redirects to to.

`[components.custom]`

oxidoc.tomltoml

[components.custom]
PromoBanner = "assets/js/promo-banner.js"
FeedbackWidget = "assets/js/feedback-widget.js"

Maps component tag names to JavaScript file paths. See Custom Components.

`[attribution]`

oxidoc.tomltoml

[attribution]
oxidoc = true

Field	Type	Default	Description
`oxidoc`	bool	`true`	Show "Built with Oxidoc" in the footer