Updated May 22, 2026

On this page

Complete reference for selfdoc.json configuration options including project settings, themes, SEO, deployment, 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.

Three fields are required: language, source, and base_url. 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/"`.
`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`	No	Search engine backend. One of: `builtin`, `fuse`, `minisearch`.
`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`	No	Author metadata. Required sub-key: `name` (string). Optional: `type` (`Person` or `Organization`), `twitter` (handle starting with `@`).
`twitter`	`string`	No	Twitter handle (starts with `@`). Overridden by `author.twitter` if both set.
`lang`	`string`	No	BCP 47 language tag for HTML `lang` attribute (e.g. `en`, `en-US`, `pt-BR`).
`lint_ignore`	`array`	No	List of SEO lint codes to suppress (e.g. `["SEO007"]`). Each entry must match the pattern `SEO` followed by digits.

#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": "minisearch",
  "min_coverage": 80,
  "author": {
    "name": "Jane Doe",
    "type": "Person",
    "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"
  }
}