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
base_url: https://doctopus.example.com
lang: en
docs_dir: docs
output_dir: out
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.

description

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

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.

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.

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:

1. Edit the light and dark variables in doctopus.yaml to change the theme values.
2. 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.