Reference
Configuration
Every key in .deepdoc.yaml, with its default.
deepdoc init writes a complete .deepdoc.yaml. Every key is optional — an
empty value means “use the built-in default”.
Project
| Key | Type | Default | What it does |
|---|---|---|---|
project_name | string | "" | Shown in the site header. Defaults to the directory name. |
description | string | "" | Short description used in prompts and metadata. |
output_dir | string | deepdoc-docs | Where generated Markdown is written. |
site_dir | string | deepdoc-site | Where the site scaffold is written. |
max_pages | number | 0 | 0 means no cap — let the planner decide. |
LLM
| Key | Type | Default | What it does |
|---|---|---|---|
llm.provider | string | "" | anthropic, openai, azure, ollama, or any LiteLLM alias. |
llm.model | string | "" | Model name, prefixed where LiteLLM requires it. |
llm.api_key_env | string | "" | Environment variable holding the key. |
llm.api_version | string | "" | Azure API version, e.g. 2024-02-01. |
llm.base_url | string | null | null | Custom endpoint. Required for Azure. |
llm.temperature | number | 0.2 | Low keeps documentation consistent. |
llm.max_tokens | number | null | null | null lets the provider decide. |
llm.context_window_tokens | number | null | null | Override the detected context window. |
llm.rate_limits.max_concurrency | number | 6 | Concurrent requests. |
llm.rate_limits.requests_per_minute | number | 60 | |
llm.rate_limits.tokens_per_minute | number | 250000 | |
llm.rate_limits.adaptive_backoff | boolean | true | Back off automatically on 429s. |
Scope
| Key | Type | Default | What it does |
|---|---|---|---|
include | string[] | [] | Glob patterns. Empty means everything not excluded. |
exclude | string[] | (a long default list) | Ships with sensible defaults for build output, dependencies and secrets. |
services | string[] | [] | Monorepo service roots, e.g. services/auth. |
languages | string[] | python, javascript, typescript, go, php, vue | Descriptive only — names the languages in prompts. Does not widen parsing. |
frameworks | string[] | [] | Descriptive only, like languages. |
Generation
| Key | Type | Default | What it does |
|---|---|---|---|
batch_size | number | 10 | Pages submitted per batch. |
max_parallel_workers | number | 6 | Concurrent LLM calls. |
rate_limit_pause | number | 0.5 | Seconds between batches. |
consistency_pass | boolean | true | Post-generation pass adding cross-page links. Costs one extra pass. |
quality.strict | boolean | false | Fail the run when pages do not validate. |
include_endpoint_pages | boolean | true | Generate API endpoint pages. |
include_integration_pages | boolean | true | Generate third-party integration pages. |
Planner
Rarely worth changing.
| Key | Type | Default | What it does |
|---|---|---|---|
max_files_per_bucket | number | 25 | Pages above this are split. |
decompose_threshold | number | 7 | Files before a page is considered for splitting. |
consolidation_similarity_threshold | number | 0.55 | Jaccard threshold for merging near-duplicate pages. |
large_file_lines | number | 500 | Above this, files get tiered summarisation. |
giant_file_lines | number | 2000 | Above this, files get clustered by feature first. |
source_context_budget | number | 200000 | Character budget before compressed evidence is used. |
Scanning
| Key | Type | Default | What it does |
|---|---|---|---|
scan.max_workers | number | 8 | Parallel file parsers. |
scan.max_source_bytes | number | 1000000 | Skip files larger than this. |
scan.max_repo_files | number | 0 | 0 means unlimited. |
scan.timeout_seconds | number | 0 | 0 means unlimited. Otherwise abort with partial results. |
scan.persistent_index | boolean | true | Cache the parse index between runs. |
Site
Everything below applies on the next deepdoc serve with no regeneration.
Each has its own guide — colours,
logo and fonts, layout,
navigation.
| Key | Type | Default | What it does |
|---|---|---|---|
site.repo_url | string | "" | Repo link and edit-page base. Falls back to your git origin remote. |
site.edit_branch | string | main | Branch for edit links. |
site.edit_path_prefix | string | "" | Path inside the repo the docs live under. |
site.logo | string | "" | Repo-relative image; replaces the project name in the navbar. |
site.logo_dark | string | "" | Optional separate dark-mode logo. |
site.favicon | string | "" | Repo-relative image; the browser-tab icon. |
site.colors.primary | string | "" | Brand colour. #rgb or #rrggbb. |
site.colors.light | string | "" | Lighter shade — the dark-mode accent. |
site.colors.dark | string | "" | Darker shade — light-mode link hover. |
site.theme.preset | string | "" | neutral, black, vitepress, ocean, catppuccin, dusk, purple. |
site.theme.tokens | object | {} | Raw design-token overrides, light and dark. |
site.theme.fonts.sans | string | "" | Google Font family. Empty means no external request. |
site.theme.fonts.mono | string | "" | Google Font family for code. |
site.theme.code_theme.light | string | github-light | Any Shiki theme. |
site.theme.code_theme.dark | string | github-dark | |
site.chrome.toc_style | string | clerk | clerk or normal. |
site.chrome.toc_depth | number[] | [2, 3] | Heading levels in the table of contents. |
site.chrome.edit_link | boolean | false | Requires a resolvable repo_url. |
site.chrome.links | object[] | [] | Extra navbar links: {text, url}. |
site.nav.sections | string[] | [] | Explicit top-level section order. |
site.nav.pin | string[] | [] | Page slugs hoisted above sections. |
site.nav.hide | string[] | [] | Removed from the sidebar; still reachable by URL. |
site.nav.rename | object | {} | {slug: "New Title"}. Also matches section titles. |
site.nav.extra | object[] | [] | Your own pages or external links. |
site.labels | object | {} | Override built-in UI strings and callout headings. |
The remaining site.chrome switches — sidebar, sidebar_default_open_level,
sidebar_collapsible, toc, breadcrumb, page_footer, last_update,
theme_switch, search, generated_meta — are all booleans defaulting to
true, except edit_link. See Layout.
Chatbot
Off by default. See Chatbot.
| Key | Type | Default | What it does |
|---|---|---|---|
chatbot.enabled | boolean | false | Scaffold and serve the Q&A backend. |
chatbot.answer.* | object | inherits llm.* | A separate model for answering. |
chatbot.embeddings.backend | string | fastembed | Local by default — no key, no external call. |
chatbot.backend.base_url | string | "" | Where the deployed backend lives. |
chatbot.backend.allowed_origins | string[] | localhost | CORS origins for your docs domain. |
Reading and writing
deepdoc config show
deepdoc config set site.theme.preset ocean
config set rejects keys that do not exist rather than silently writing a
setting that does nothing:
Error: Unknown config key: site.theme.presset
Did you mean:
site.theme.preset