Using custom CSS and fonts

In cases where customizing only the colors of your docs isn't enough, we allow adding your own custom CSS for further customization.

Note: don't rely on any classes generated by Doctave as they're subject to change and doing so may break your docs.

Custom CSS

You can tell Doctave to include your own custom CSS files in your site, which gives you a lot of freedom to customize the look of your site.

To include a CSS file:

1. Place the file in your _assets directory (for example _assets/styles.css).
2. Specify the CSS file in your doctave.yaml

You can specify your styles in your doctave.yaml file under the styles key:

title: My Docs
...
styles:
  - _assets/styles.css

Note that:

• The CSS file must to be in the _assets directory
• The file must be a plain CSS file, and can't include for example SASS syntax
• Inline style with a style tag isn't supported

Using theme colors in CSS

The theme colors are all accessible as CSS variables.

Each variable is dark-mode aware, meaning it will change depending on if the reader is using light or dark mode, while retaining the correct contrast. You can try this by toggling your color mode on this page and watch the scale below change.

To access your theme's accent color scale, you can use the --accent-* variables using a number between 1 and 12 (for example --accent-8).

To access your theme's grayscale, you can use the --gray-* variables using a number between 1 and 12 (for example --gray-8).

You can also use the --accent-contrast and --gray-contrast variables for a color that works as a contrast to solid gray/accent colors

/* Custom card styling */
.custom-card {
  color: var(--accent-contrast);
  background: var(--accent-9);
}

Custom Fonts

By default Doctave falls back to the reader's operating system's native font. This gives a generally clean and modern look on all platforms, but you can alternatively provide your own font for Doctave to use.

Doctave uses CSS variables to set fonts in your documentation. This also lets you easily set fonts for specific elements, such as headings, in your documentation.

Setting fonts on specific elements

Below is a list of supported CSS variables, and what elements they impact.

To use a specific font, set the appropriate CSS variable in a CSS file:

:root {
  --doctave-default-font-family: "Comic Sans MS";
}

Example

Let's walk through an example. Say you want to make your documentation a bit more space-like, and decide you want to use the Nasalization font in your docs.

The first step is to get a copy of the font.

Loading the custom font

First, download the font definition. In our case we're given a single file called nasalization-rg.otf. Place this in your project's _assets directory.

Next, in your custom CSS file (such as _assets/styles.css), create a @font-face declaration at the top of the file (see above about how to create a custom CSS file).

@font-face {
  font-family: 'Nasalization';
  src: url('/_assets/nasalization-rg.otf') format("opentype");
}

Two important things to note:

1. Ensure you prefix the path to the font with a slash, so it's loaded from the root of the domain
2. Check that your format matches the font definition type you are dealing with.

If you want to learn more, we recommend this crash course on using custom fonts

Using the custom font

Now you are ready to use your custom font in your docs!

To do this, you can set specific CSS variables to set the font for specific parts of your docs.

If you want to set the font for all content, use --doctave-default-font-family.

:root {
  --doctave-default-font-family: "Nasalization";
}

To target headings only, use --doctave-default-font-family.

:root {
  --doctave-heading-font-family: "Nasalization";
}

You should now see your custom font rendered.