Settings reference

Every key Readsmith's configuration accepts, in one place. All keys are optional except site.name. The same shape is accepted from docs.yaml, docs.yml, or a docs.json (the last is accepted for migration).

site

Key	Type	Default	What it does
`site.name`	string	required	The site's name: header wordmark, metadata, agent outputs
`site.url`	string	unset	Canonical base URL; enables absolute URLs in the sitemap, RSS, llms.txt, and page metadata
`site.description`	string	unset	One-line description for metadata and the agent outputs
`site.logo`	string or `{light, dark}`	unset	Header logo, served from your content; a pair switches with the theme, flash-free
`site.favicon`	string or `{light, dark}`	unset	Favicon; a pair follows the visitor's OS scheme; without it Readsmith serves its default mark
`site.author`	`{name, url?}`	unset	Emitted as JSON-LD author on pages
`site.publisher`	`{name, url?}`	unset	Emitted as JSON-LD publisher on pages
`site.theme`	object	unset	Brand color and font tokens; see Theming

appearance

Key	Type	Default	What it does
`appearance.default`	`system`, `light`, `dark`	`system`	First-visit color scheme; a visitor's own toggle choice persists and wins

content

Key	Type	Default	What it does
`content.root`	string	`.`	Directory that holds the pages, relative to where the config lives
`content.include`	string[]	`*/.md`, `*/.mdx`	Glob patterns for page discovery
`content.exclude`	string[]	see below	Extra ignore patterns; merged with the defaults, never replacing them
`content.home`	string	unset	The page served at `/`; may escape the content root (`../README.md`), never the repository

Always excluded, regardless of content.exclude: **/node_modules/**, **/.git/**, and the reserved snippets/** directory.

Key	Type	Default	What it does
`navigation`	list	auto	Sidebar order: page slugs and `{group, pages}` nests; omit it to auto-build from the file tree
`navigation[].group`	`{group, pages, icon?, tag?, expanded?}`	—	A titled group; `icon` (a Lucide name), `tag` (badge text), `expanded` (open by default)
`tabs`	list of `{tab, pages?, icon?, menu?}`	unset	Top-level tabs; each scopes the sidebar; `icon` (a Lucide name); `menu` makes the tab a dropdown
`tabs[].menu[]`	`{item, pages, icon?}`	—	A dropdown destination within a tab, with its own pages

Details and examples: Navigation and tabs.

apiReference

Key	Type	Default	What it does
`apiReference.spec`	string	required to enable	Path to your OpenAPI file, relative to the content root
`apiReference.path`	string	`/api-reference`	URL the reference mounts at
`apiReference.label`	string	`API Reference`	Label for the tab or header link
`apiReference.layout`	`single`, `pages`	`single`	One continuous page, or one page per operation with an overview at the root

assets and links

Key	Type	Default	What it does
`assets`	list of `{from, to}`	unset	Directories to publish; `from` may escape the content root, never the repository
`links.repo`	string	unset	Repository URL; relative links that leave the docs resolve to files on the forge
`links.branch`	string	`main`	Branch used when building forge links

variables

Key	Type	Default	What it does
`variables`	map	unset	Values available in every page: `{{name}}` in Markdown, `{name}` in MDX

Key	Type	Default	What it does
`footer.socials`	map of platform to URL	unset	Social links in the content footer, e.g. `github`, `x`
`branding`	boolean	`true`	Shows the "Powered by Readsmith" badge; set `false` to white-label

security

Key	Type	Default	What it does
`security.csp.imgSrc`	string[]	unset	Extra Content-Security-Policy sources for images
`security.csp.connectSrc`	string[]	unset	Extra sources for fetch and websocket connections
`security.csp.fontSrc`	string[]	unset	Extra font sources
`security.csp.frameSrc`	string[]	unset	Extra frame sources (embeds)
`security.csp.frameAncestors`	string[]	unset	Who may frame your docs

Sources add to the strict default policy; they never replace it. Tokens containing whitespace or ; are dropped.

mcp

Key	Type	Default	What it does
`mcp.path`	string	`/mcp`	The MCP endpoint's public alias; the canonical endpoint always answers regardless

contextual

Key	Type	Default	What it does
`contextual.options`	string[]	all of them	Which items the per-page actions menu shows: `copy`, `view`, `chatgpt`, `claude`, `perplexity`, `cursor`, `vscode`, `mcp`. Order is honored

See Page actions and agent connect for what each option does.

ai

The ai block configures search, Ask AI, and MCP behavior. API keys are never written here; they come from the environment.

Key	Type	Default	What it does
`ai.chat.provider`	`openai`, `anthropic`, `google`, `gateway`	unset	Chat model provider for Ask AI
`ai.chat.model`	string	unset	Chat model id
`ai.embedding.provider`	`openai`, `google`, `gateway`	unset	Embedding provider for semantic search
`ai.embedding.model`	string	unset	Embedding model id
`ai.search.rrfK`	integer	`60`	Rank-fusion constant for hybrid search
`ai.search.topK`	integer	`8`	Results returned per search
`ai.askAi.enabled`	boolean	`true`	Turns the Ask AI answerer on or off (search stays independent)
`ai.askAi.maxSteps`	integer	`4`	Tool-use steps the answerer may take
`ai.askAi.maxOutputTokens`	integer	`1024`	Answer length ceiling
`ai.askAi.timeoutMs`	integer	`30000`	Per-question time budget
`ai.askAi.instructions`	string	unset	Owner guidance appended to the system prompt (voice, tone, scope only; never overrides the base rules of answering from the docs and citing sources)
`ai.askAi.sections`	string[]	unset	Restrict retrieval to these top-level sections (a page path's first segment); omitted = the whole site
`ai.analytics.retentionDays`	integer	`90`	How long Ask AI question records are kept
`analytics.ga4.measurementId`	string	unset	Google Analytics 4 tag, injected with matching CSP (Analytics)
`analytics.posthog.apiKey`	string	unset	PostHog project key; `analytics.posthog.host` overrides the US cloud default
`analytics.plausible.domain`	string	unset	Plausible site domain; `analytics.plausible.src` overrides the script source
`analytics.fathom.siteId`	string	unset	Fathom site id
`security.csp.scriptSrc`	string[]	`[]`	Extra script-src hosts beyond what configured analytics add automatically
`ai.limits.ask`	`{limit, windowMs}`	`10` per minute	Rate limit for Ask AI requests
`ai.limits.search`	`{limit, windowMs}`	`60` per minute	Rate limit for search requests
`ai.limits.mcp`	`{limit, windowMs}`	`60` per minute	Rate limit for MCP requests

Environment variables override ai.limits at deploy time, and a missing embedding key degrades search to keyword-only rather than breaking it.