Sign Up

Doctave 2.0 Migration Guide

We're tried to make it as easy as possible to migrate your documentation to the new version. This guide will walk you through the process of migrating your documentation over to Doctave 2.0.

Updating your doctave.yaml

The first step is to update your project to use Doctave 2.0 in your doctave.yaml:

Update the version field to 2

title: Acme Docs
version: 2      # <= Add this line

# of your config

Note: This will cause your project to have errors. Not to worry! We will walk through how to fix the issues step by step.

This will cause a number of issues to show up in Doctave Studio. Let's walk through the changes you have to make.

Update your theme

The color, logo, and favicon fields are moved under a new theme field in 2.0.

Let's update this:

  • Create a new theme field
  • Move the color, logo, and favicon fields under it
  • Update your main color to accent in the color object
  main: "#FA5B30"
  main_dark: "#FA5B30"

  src: _assets/favicon.ico

  src: _assets/logo.svg
  src_dark: _assets/logo-dark.svg

Doctave now computes a color palette for both light and dark mode from your main brand color.

Migrate your structure.yaml to doctave.yaml

The structure.yaml is deprecated in 2.0 and your tab configuration is moved into your doctave.yaml under a tabs field.

The structure of the tabs field is also slightly changed: you no longer have to mention subtabs unless you visually want to have a subtab in your docs.

  - label: Guides
      - label: Guides
        path: /
  - label: API Reference
      - label: References
        path: /reference/
  - label: Libraries & SDKs
    - label: Overview
      path: /sdks/
    - label: Python
      path: /sdks/python/
        set: devicon
        name: python
    - label: Ruby
      path: /sdks/suby/
        set: devicon
        name: ruby

Updating your content

Next is your actual content. The amount of effort needed to migrate depends on how much you use Liquid components, as they will have to be migrated to the new component syntax.

Liquid changes

The Liquid template syntax is no longer supported in Doctave 2.0. You will have to migrate your Liquid partials to Doctave's new component syntax.

Opt-in to backwards compatibility mode

To make your migration easier, you can opt-in to the legacy liquid engine on a per-page basis by adding the following attributes to your Markdown file's frontmatter:
  v2_templates: false


Markdown changes

If you are only using standard Markdown in your pages, there is very little you need to do any more!

The only change that can impact you is Doctave no longer supports indented code blocks. We chose to disable this Markdown feature in order to support nicer indentation in the new component syntax.

This is easy to update:
## Code example

    if (powerlevel > 9000) {
      throw "I can't be that high"

Was this page helpful?