Project Configuration Reference

This document explains the available configuration options in the doctave.yaml file.

Configuration Example

An example doctave.yaml demonstrating the available configuration options.

---
title: Doctave Docs
logo:
  src: _assets/doctave-logo.svg
  src_dark: _assets/doctave-logo-dark.svg
colors:
  main: "#7B8FFE"
color_mode: auto
favicon:
  src: _assets/favicon.ico
open_api:
  - spec_file: http-spec.json
    uri_prefix: /api
user_preferences:
  tier:
    label: Tier
    default: Starter
    values:
      - Starter
      - Growth
      - Enterprise
header:
  cta:
    external: https://dashboard.doctave.com/users/register
    label: Sign Up
  links:
    - external: https://doctave.com
      label: What's Doctave?
styles:
  - _assets/style.css
redirects:
  - from: /docs/old/path
    to: /docs/new/path

Reference

Below are explanations of all the objects and their fields in the project configuration. Your doctave.yaml should contain a list of these objects.

Title

The title property is a string which defines the project title.

Logo

The logo property is a map that specifies the logo for the project.

field	description	required?	default
`src`	Path to image within `_assets` directory	true
`src_dark`	Path to image to use in dark mode	false

Favicon

The favicon property is a map that specifies the favicon for the project.

field	description	required?	default
`src`	Path to image within `_assets` directory	true

OpenApi

The open_api property is a list of Source definitions.

Source

field	description	required?	default
`spec_file`	Path to OpenAPI specification file	true
`uri_prefix`	Path to the generated OpenAPI pages in your docs	false

Colors

The colors object can be used to update the color scheme of your documentation.

Variables

The following color variables are available:

field	description	required	default
`main`	Main brand color	false	#7B8FFE
`main-contrast`	Contrast color for the main brand color	false	#FFFFFF
`text-base`	Main text color	false	#475569
`text-strong`	Color of emphasized text	false	#1E293B
`text-soft`	Color of de-emphasized text	false	#94A3B8
`bg`	Background color for the page	false	#FFFFFF
`bg-secondary`	Secondary background (for example code blocks)	false	#F8FAFC
`border`	Color used for various borders	false	#E2E8F0

You can use the -dark prefix to specify their dark mode versions:

field	description	required	default
`main-dark`	Main brand color	false	#7B8FFE
`main-contrast-dark`	Contrast color for the main brand color	false	#FFFFFF
`text-base-dark`	Main text color	false	#cbd5e1
`text-strong-dark`	Color of emphasized text	false	#f8fafc
`text-soft-dark`	Color of de-emphasized text	false	#64748b
`bg-dark`	Background color for the page	false	#0F172A
`bg-secondary-dark`	Secondary background (for example code blocks)	false	#1E293B
`border-dark`	Color used for various borders	false	#334155

Section specifier

The above colors can be given a header-, nav-, or content- prefix to scope them to only a specific part of the page.

Color Mode

The color_mode property is used to control which color schemes are available for your site. By default it's set to auto.

When color mode is

light: your site will use the light theme and it can't be toggled
dark: your site will use the dark theme and it can't be toggled
auto: your site will use system theme and it can be toggled

User Preferences

The user_preferences property is a map of preference definitions.

Preference

field	description	required?
`label`	Label for selector	true
`default`	Default value	true
`values`	Possible values as strings or User Preference Option objects	true

User Preference Option

field	description	required?	default
`label`	Label for User Preference Option	true
`value`	Key for User Preference Option	true

Styles

The styles property is a list of paths to stylesheets in the _assets directory.

Header

Header contains settings for your header bar at the top of your site.

field	description	required?	default
`links`	An array of external links that will be placed on the header at the top of your site.	false
`cta`	Call-to-action button that will be placed on the header at the top of your site.	false

Header Link

field	description	required?	default
`label`	Label that will be displayed in your header link.	true
`external`	An external url where the user will navigate upon clicking the link	true

Header Call-To-Action

field	description	required?	default
`label`	Label that will be displayed in your call-to-action button.	true
`external`	An external url where the user will navigate upon clicking the button	true

Redirects

The redirects property is a list of Redirect objects.

Redirect

The redirect object contains the source and destination urls of a single redirect.

field	description	required?	default
`from`	A url path from where the redirect will be activated.	true
`to`	A url path to where the redirect will lead to.	true