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`

doctave.yaml

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

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

doctave.yaml

colors:
  main: "#FA5B30"
  main_dark: "#FA5B30"

favicon:
  src: _assets/favicon.ico

logo:
  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.

structure.yaml

tabs:
  - label: Guides
    subtabs:
      - label: Guides
        path: /
  - label: API Reference
    subtabs:
      - label: References
        path: /reference/
  - label: Libraries & SDKs
    subtabs:
    - label: Overview
      path: /sdks/
    - label: Python
      path: /sdks/python/
      icon:
        set: devicon
        name: python
    - label: Ruby
      path: /sdks/suby/
      icon:
        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:

README.md

---
experimental:
  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: