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

# ...rest of your config

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

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

favicon:
  src: _assets/favicon.ico

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

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.

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:

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

## Code example

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