--- description: Doctopus build configuration. --- # 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.frankmayer.dev/) 🐙 base_url: https://doctopus.example.com lang: en docs_dir: docs output_dir: out minify: enabled 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. ### `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`](./hooks.md) 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: 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.