# Configuration

Doctopus reads its site configuration from `doctopus.yaml`.

You can generate a starter configuration with:

```bash
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

```yaml
title: doctopus
description: A simple documentation generator
footer: Built with [doctopus](https://doctopus.pages.dev/) 🐙
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.

### `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.

### `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.