Navigation Migration

This guide explains how to migrate existing configurations that used topNavigation, sidebar and customPages to the new unified navigation configuration introduced in vNEXT.

Overview

Navigation is now configured through a single navigation array. Items at the root level become top navigation tabs, while nested categories automatically form the sidebar. Custom pages are added using the custom-page item type.

Before and After

Before
 
const config: ZudokuConfig = {
  topNavigation: [
    { id: "docs", label: "Docs" },
    { id: "api", label: "API" },
  ],
  sidebar: {
    docs: [{ type: "doc", id: "introduction" }],
  },
  customPages: [{ path: "/playground", render: Playground, prose: false }],
  apis: {
    type: "file",
    input: "./openapi.json",
    navigationId: "api",
  },
};

After
 
const config: ZudokuConfig = {
  navigation: [
    {
      type: "category",
      label: "Docs",
      items: ["introduction"],
    },
    {
      type: "custom-page",
      path: "/playground",
      element: <Playground />,
    },
    {
      type: "link",
      to: "/api",
      label: "API",
    },
  ],
  apis: [
    {
      path: "/api",
      type: "file",
      input: "./openapi.json",
    },
  ],
};

Migration steps

1. Create a navigation array

   Move all items from topNavigation and your sidebar into a new navigation array.

2. Convert custom pages

   Replace entries in customPages with type: "custom-page" items inside navigation.

3. Update plugin configs

   Replace all uses of navigationId with path in plugin options like apis or catalogs. Navigation items of type link should use the to property to reference the path of the API or catalog.

4. Reference plugin paths in navigation

   Items produced by plugins are not added automatically. Add links or categories in your navigation so users can access them.