Reference

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

KeyTypeDefaultWhat 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

KeyTypeDefaultWhat 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

KeyTypeDefaultWhat 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

KeyTypeDefaultWhat 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.

KeyTypeDefaultWhat 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

KeyTypeDefaultWhat 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.

KeyTypeDefaultWhat 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.

KeyTypeDefaultWhat 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

Edit this page on GitHub