Updated August 12, 2026

On this page

Complete reference for selfdoc.json configuration options including project settings, themes, SEO, deployment, example validators, and branding.

#Configuration

selfdoc is configured via a selfdoc.json file in your project root. Run selfdoc init to generate a starter config interactively, or create one manually.

base_url is the only required field. source is optional -- a codeless project (a portfolio or personal site that is nothing but Markdown pages) declares none, and directives that extract from source code are then a hard error rather than an empty section. Everything else is optional and has sensible defaults.

Warning

base_url is required for deployment. Without it, canonical URLs, sitemaps, OG tags, and Atom feeds will have broken links. Set it to the URL where your site will be hosted (e.g., https://myproject.pages.dev).

#Config Reference

The table below lists every field recognized by selfdoc.json, including the field type, whether it is required, and a description of what it controls. Required fields have no default and must be provided explicitly.

#Core

Core
Key	Type	Required	Description
`language`	`string`	Yes	Source language. One of: `python`, `go`, `typescript`, `javascript`.
`source`	`array`	Yes	Non-empty list of source directory paths to scan.
`base_url`	`string`	Yes	Site base URL (e.g. `https://example.com`). Trailing slash is stripped.
`docs`	`string`	No	Directory containing Markdown templates. Default: `"docs/"`.
`output`	`string`	No	Build output directory. Default: `"docs/_build/"`.
`changelog`	`string`	No	Path to the changelog document published as the site's changelog page, relative to the project root. Absent, the project root's `CHANGELOG.md` is used if it exists; declare it when that file is not this site's changelog (a workspace root that rolls up several independently versioned projects, say). A declared path that does not exist is a build error.
`repo`	`string`	No	GitHub repository URL. Enables source links in generated pages.
`branch`	`string`	No	Git branch for source links. Used with `repo`.
`description`	`string`	No	Project description used in site metadata and SEO tags.
`directives`	`object`	No	Map of custom directive names to script paths (relative to project root). Default: `{}`.

#Features

Features
Key	Type	Required	Description
`theme`	`string`	No	Theme name. Default: `"minimal"`.
`search`	`string`	No	Search UI style. One of: `icon`, `bar`, `hidden`.
`search_engine`	`string`	Yes	Search engine that answers the site's search UI. Required, with no default: the only valid value is `pagefind`.
`feedback`	`object`	No	Page feedback widget. Must contain at least one of `webhook` (URL string) or `ga` (Google Analytics ID string).
`auto_detect`	`object`	No	Auto-detection toggles. Valid keys: `steps` (bool), `api_entries` (bool).
`min_coverage`	`integer`	No	Minimum documentation coverage (0--100). `selfdoc check` fails if coverage is below this threshold.

#SEO

SEO
Key	Type	Required	Description
`author`	`object`	Yes	The site's author, emitted as one `Person` in every page's structured data. Required sub-keys: `name` and `url`. Optional: `same_as` (list of external identity URLs). There is no inferred author.
`twitter`	`string`	No	Twitter/X handle (starts with `@`) for the `twitter:site` meta tag.
`lang`	`string`	No	BCP 47 language tag for HTML `lang` attribute (e.g. `en`, `en-US`, `pt-BR`).
`lint_ignore`	`array`	No	List of warning-severity lint codes to suppress (e.g. `["SEO007"]`). Error-severity codes are refused at load: an error means the build is wrong, so it cannot be silenced.

#Deploy

Deploy
Key	Type	Required	Description
`deploy.provider`	`string`	When `deploy` is present	Deploy provider. One of: `cloudflare-pages`, `github-pages`.
`deploy.project`	`string`	For `cloudflare-pages`	Cloudflare Pages project name.

#Branding

Branding
Key	Type	Required	Description
`branding.tagline`	`string`	No	Hero tagline displayed on the landing page.
`branding.cta_text`	`string`	No	Primary call-to-action button text.
`branding.cta_link`	`string`	No	Primary call-to-action button URL.
`branding.secondary_cta_text`	`string`	No	Secondary call-to-action button text.
`branding.secondary_cta_link`	`string`	No	Secondary call-to-action button URL.
`branding.logo`	`string`	No	Path to logo image.
`branding.features`	`array`	No	List of feature cards for the landing page. Each item must have `title` (string) and `description` (string).

#Generation

Generation
Key	Type	Required	Description
`gen.exclude`	`array`	No	List of module paths to exclude from `selfdoc gen` output.
`gen_data`	`object`	No	Data generation configuration. Contains `scripts`: a list of objects with `command` (string), `output` (string), and `mounts` (list of strings).

#Common Configurations

#Minimal Python project

json

{
  "language": "python",
  "source": ["src/"],
  "base_url": "https://myproject.pages.dev"
}

#Go project with deployment

json

{
  "language": "go",
  "source": ["pkg/", "internal/"],
  "base_url": "https://myproject.pages.dev",
  "repo": "https://github.com/user/myproject",
  "branch": "main",
  "deploy": {
    "provider": "cloudflare-pages",
    "project": "myproject"
  }
}

#Full-featured project with branding

json

{
  "language": "python",
  "source": ["mylib/"],
  "base_url": "https://mylib.dev",
  "docs": "docs/",
  "output": "docs/_build/",
  "description": "A toolkit for building great things.",
  "repo": "https://github.com/user/mylib",
  "branch": "main",
  "lang": "en",
  "theme": "minimal",
  "search": "bar",
  "search_engine": "pagefind",
  "min_coverage": 80,
  "author": {
    "name": "Jane Doe",
    "url": "https://janedoe.example",
    "same_as": ["https://github.com/janedoe"]
  },
  "twitter": "@janedoe",
  "deploy": {
    "provider": "cloudflare-pages",
    "project": "mylib"
  },
  "branding": {
    "tagline": "Build great things.",
    "cta_text": "Get Started",
    "cta_link": "getting-started/",
    "features": [
      {
        "title": "Fast",
        "description": "Blazing fast builds with zero dependencies."
      },
      {
        "title": "Flexible",
        "description": "Works with Python, Go, and TypeScript projects."
      }
    ]
  },
  "directives": {
    "changelog": "scripts/changelog-directive.py"
  }
}

#Example Validators

The examples key maps a fenced-block language to the command that validates a snippet written in it. selfdoc check uses these commands for code blocks marked validate in their fence info string, writing each block to a scratch file and substituting its path for {file}:

json

{
  "examples": {
    "python": "uv run --directory python python {file}",
    "go": "scripts/validate-example-go.sh {file}",
    "ts": "scripts/validate-example-ts.sh {file}"
  }
}

Every command template must contain the {file} placeholder; a template without it is rejected when the config loads, since it would validate nothing. Keys are language names exactly as they appear after the opening fence, so a block opened with ```py needs a py entry, not a python one. Omitting examples entirely turns the feature off, and any validate marker in the docs then reports EXAMPLE003. See the Check Guide for the full behavior.