Configuration

Doctopus reads its site configuration from doctopus.yaml.

You can generate a starter configuration with:

doctopus init

That command creates a default doctopus.yaml you can edit for your project.

How It Works

When Doctopus builds the site, it loads doctopus.yaml and uses it to configure the generated output.

The light and dark sections are converted into CSS custom properties and prepended to the stylesheet. That means your configured variables are available to the default stylesheet and to your own custom stylesheet.

Doctopus uses a built-in default stylesheet unless you provide your own docs/style.css. If docs/style.css exists, it is used instead of the default stylesheet.

Example

title: doctopus
description: A simple documentation generator
footer: Built with [doctopus](https://doctopus.frankmayer.dev/) 🐙
base_url: https://doctopus.example.com
lang: en
docs_dir: docs
output_dir: out
minify: enabled
versioning:
  mode: from_git_tags
  from: ">= 0.3.0"
  current: next
hooks:
  pre_build: ["uv", "run", "--script", "hooks/pre_build.py"]
  post_build: ["uv", "run", "--script", "hooks/post_build.py"]
light:
  --accent-color: oklch(60% 0.118 184.704)
  --background-alt-color: oklch(96.3% 0.002 197.1)
  --background-color: oklch(98.7% 0.002 197.1)
  --border-color: oklch(72.3% 0.014 214.4)
  --code-background-color: oklch(92.5% 0.005 214.3)
  --foreground-color: oklch(14.8% 0.004 228.8)
dark:
  --accent-color: oklch(50.8% 0.118 165.612)
  --background-alt-color: oklch(21.8% 0.008 223.9)
  --background-color: oklch(14.8% 0.004 228.8)
  --border-color: oklch(45% 0.017 213.2)
  --code-background-color: oklch(21.8% 0.008 223.9)
  --foreground-color: oklch(98.7% 0.002 197.1)

Options

`title`

The site title. This is used as the overall name of the generated documentation site.

You can override the title per page by setting the title frontmatter variable.

`description`

The site description. This is used in the generated HTML metadata.

You can override the description per page by setting the description frontmatter variable.

`footer`

The site footer in Markdown. This is at the bottom of every page.

`base_url`

The canonical base URL for the site, for example https://docs.example.com. Use the final public URL where the generated site will be hosted.

`platform`

The platform to build for. Currently only cloudflare_pages is supported. This is used to generate the correct caching headers.

`lang`

The language code for the generated HTML document, such as en.

`docs_dir`

The directory that contains your source documentation files. Doctopus reads markdown pages, index.*, and optional assets such as style.css from this directory.

`output_dir`

The directory where the generated static site is written.

`minify`

Controls build minification. Doctopus accepts the string values enabled and disabled.

Use enabled to minify generated output.

Use disabled if you want easier-to-read build output while debugging.

`versioning`

Controls whether Doctopus generates versioned documentation.

If versioning is omitted, versioning is disabled and Doctopus builds only the files from docs_dir without adding a version prefix to URLs.

versioning:
  mode: from_git_tags
  from: ">= 0.3.0"
  current: next

Supported keys:

mode
from
current

`versioning.mode`

Selects where versioned documents come from.

Supported values:

from_directories
from_git_tags

from_directories treats directories inside docs_dir as already-versioned documentation sources.

from_git_tags reads documentation from Git tags. Each tag becomes a generated URL prefix, so a page like guide/install.md in tag v1.2.3 is generated as /v1.2.3/guide/install/.

Git tag sources read Markdown and referenced media from the same Git object. Shared site files such as the homepage, stylesheet, and favicon still come from the current filesystem checkout.

`versioning.from`

Optional semver constraint for from_git_tags.

Only Git tags matching the constraint are included.

Example:

versioning:
  mode: from_git_tags
  from: ">= 0.3.0"

This includes v0.3.0, v0.3.1, v1.0.0, and newer matching versions. Older versions are skipped.

`versioning.current`

Optional URL prefix for the current filesystem documentation.

The value must be a single relative path segment such as next or latest.

When set, Doctopus includes the current docs_dir content in addition to the selected versioned sources.

Example:

versioning:
  mode: from_git_tags
  current: next

With this configuration, docs_dir/guide/install.md is generated as /next/guide/install/.

Homepage links to Markdown pages are version-aware. If current is set, homepage links point to the current prefix. If current is not set and mode is from_git_tags, homepage links point to the newest semver Git tag.

`hooks`

Optional commands to run before and after each build.

Each hook is an argv array. The first item is the executable and the remaining items are passed as arguments. Hooks run from the directory that contains doctopus.yaml, so relative paths are resolved from your project root.

Supported hook keys:

pre_build
post_build

See hooks for examples and recommendations.

`light`

CSS custom properties for the light color scheme. Each key should be a CSS variable name such as --accent-color.

These variables are written into a :root block.

`dark`

CSS custom properties for the dark color scheme. Each key should be a CSS variable name such as --accent-color.

These variables are written into a @media (prefers-color-scheme: dark) block.

Styling Notes

If you want to customize the site styles:

Edit the light and dark variables in doctopus.yaml to change the theme values.
Add docs/style.css if you want to replace the built-in stylesheet entirely.

Because the configured CSS variables are prepended to the stylesheet, both the default stylesheet and your custom docs/style.css can reference them.