logo
On this page

Sidebar

You can configure a sidebar to manage your documentation, which is useful to:

  • Group multiple related documents
  • Display a sidebar on each of those documents

To use sidebars on your Docuo site:

  1. Define a file that contains a dictionary of sidebar objects.
  2. Use the sidebar key in the file in docSidebar item type of navbar.
docuo.config.json
{
  "themeConfig": {
    "navbar": {
      "items": [
        {
          "type": "docSidebar",
          "label": "Docs",
          "sidebarIds": ["mySidebar"],
          "position": "left"
        }
      ]
    }
  }
}
1
Copied!
sidebars.json
{
  "mySidebar": [
    {
      "type": "category",
      "label": "Overview",
      "items": ["overview/introduction"]
    },
    {
      "type": "link",
      "label": "Learn more",
      "href": "https://example.com"
    }
  ]
}
1
Copied!

There are four types of sidebar items including doc, category, link, and autogenerated.

ItemRendered Output
DocLink to a doc page, associating it with the sidebar
LinkLink to any internal or external page
CategoryCreate a dropdown of sidebar items
AutogeneratedGenerate a sidebar slice automatically

Use the doc type to link to a doc page and assign the doc to a sidebar:

type.ts
type SidebarItemDoc =
  // Normal syntax
  | {
      type: "doc";
      id: string;
      label: string; // Sidebar label text
    }

  // Shorthand syntax
  | string; // docId shortcut
1
Copied!

id represents the unique identifier of a doc page, which is a string generated from the path of the doc page relative to the docs directory. The string is uniformly processed into pure lowercase, and spaces are replaced with -

Here's an example:

sidebars.json
{
  "mySidebar": [
    // Normal syntax
    {
      "type": "doc",
      "id": "overview/basic-features", // document ID
      "label": "Basic features" // sidebar label
    },

    // Shorthand syntax
    "overview/introduction" // document ID
  ]
}
1
Copied!

If you use the doc shorthand or autogenerated sidebar, you would lose the ability to customize the sidebar label through item definition.

WARNING

A doc item sets an implicit sidebar association. Don't assign the same doc to multiple sidebars.

Use the link type to link to any page (internal or external) that is not a doc.

type.ts
type SidebarItemLink = {
  type: "link";
  label: string;
  href: string;
};
1
Copied!

Here's an example:

sidebars.json
{
  "myLinksSidebar": [
    // External link
    {
      "type": "link",
      "label": "Facebook", // The link label
      "href": "https://facebook.com" // The external URL
    },

    // Internal link
    {
      "type": "link",
      "label": "Home", // The link label
      "href": "/" // The internal path
    }
  ]
}
1
Copied!

Category: create a hierarchy

Use the category type to create a hierarchy of sidebar items.

type.ts
type SidebarItemCategory = {
  type: "category";
  label: string; // Sidebar label text.
  items: SidebarItem[]; // Array of sidebar items.
};
1
Copied!

Here's an example:

sidebars.json
{
  "mySidebar": [
    {
      "type": "category",
      "label": "Editing docs",
      "items": [
        "editing-docs/docs-components",
        {
          "type": "category",
          "label": "Managing docs",
          "items": [
            "editing-docs/managing-docs/sidebar",
          ]
        }
      ]
    }
  ]
}
1
Copied!
TIP

Use the shorthand syntax when you don't need customizations:

sidebars.json
{
  "mySidebar": {
    "Editing docs": [
      "editing-docs/docs-components",
      {
        "Managing docs": ["editing-docs/managing-docs/sidebar"]
      }
    ]
  }
}
1
Copied!

Using shorthands

You can express typical sidebar items without much customization more concisely with shorthand syntaxes. There are two parts to this: doc shorthand and category shorthand.

Doc shorthand

An item with type doc can be simplified to a string to represent its ID:

sidebars(Longhand)
sidebars(Shorthand)
{
  "mySidebar": [
    {
      "type": "doc",
      "id": "overview/introduction"
    }
  ]
}
1
Copied!
{
  "mySidebar": ["overview/introduction"]
}
1
Copied!

So it's possible for you to simplify the example above to:

sidebars.json
{
  "mySidebar": [
    {
      "type": "category",
      "label": "Overview",
      "items": ["overview/introduction"]
    },
    {
      "type": "link",
      "label": "Learn more",
      "href": "https://example.com"
    }
  ]
}
1
Copied!

Category shorthand

A category item can be represented by an object whose key is its label, and the value is an array of subitems.

sidebars(Longhand)
sidebars(Shorthand)
{
  "mySidebar": [
    {
      "type": "category",
      "label": "Overview",
      "items": ["overview/introduction", "overview/basic-features"]
    }
  ]
}
1
Copied!
{
  "mySidebar": [
    {
      "Overview": ["overview/introduction", "overview/basic-features"]
    }
  ]
}
1
Copied!

This allows you to simplify the example to:

sidebars.json
{
  "mySidebar": [
    {
      "Overview": ["overview/introduction"]
    },
    {
      "type": "link",
      "label": "Learn more",
      "href": "https://example.com"
    }
  ]
}
1
Copied!

Each shorthand object after this transformation will contain exactly one entry. Now consider the further simplified example below:

sidebars.json
{
  "mySidebar": [
    {
      "Overview": ["overview/introduction"],
      "Getting started": ["getting-started/quickstart", "getting-started/development"]
    },
    {
      "type": "link",
      "label": "Learn more",
      "href": "https://example.com"
    }
  ]
}
1
Copied!

Autogenerated

Docuo can create a sidebar automatically from your filesystem structure: each folder represents a sidebar category, and each file generates a doc link.

type.ts
type SidebarItemAutogenerated = {
  type: "autogenerated";
  dirName: string; // Source folder to generate the sidebar slice from (relative to docs)
};
1
Copied!

Docuo can generate a full sidebar from your docs folder:

sidebars.json
{
  "myAutogeneratedSidebar": [
    {
      "type": "autogenerated",
      "dirName": "." // "." means the current docs folder
    }
  ]
}
1
Copied!

An autogenerated item is converted by Docuo to a sidebar slice (discussed in category shorthand): a list of items of type doc or category. So you can splice multiple autogenerated items from multiple directories, interleaving them with regular sidebar items, in one sidebar level.

Default sidebar

If the sidebarPath is unspecified, Docuo automatically use a default sidebar for you by using the filesystem structure of the docs folder:

sidebars.json
{
  "mySidebar": [
    {
      "type": "autogenerated",
      "dirName": "." // generate sidebar from the docs folder
    }
  ]
}
1
Copied!

You can also define your sidebars explicitly.

A sidebar at its crux is a hierarchy of categories, doc links, and other hyperlinks.

type.ts
type Sidebar =
  // Normal syntax
  | SidebarItem[]
  // Shorthand syntax
  | { [categoryLabel: string]: SidebarItem[] };
1
Copied!

For example:

sidebars.json
{
  "mySidebar": [
    {
      "type": "category",
      "label": "Getting Started",
      "items": [
        {
          "type": "doc",
          "id": "getting-started/quickstart"
        }
      ]
    },
    {
      "type": "category",
      "label": "Overview",
      "items": [
        {
          "type": "doc",
          "id": "overview/introduction"
        },
        {
          "type": "doc",
          "id": "overview/basic-features"
        }
      ]
    },
    {
      "type": "link",
      "label": "Learn more",
      "href": "https://example.com"
    }
  ]
}
1
Copied!

This is a sidebars file that exports one sidebar, called mySidebar. It has three top-level items: two categories and one external link. Within each category, there are a few doc links.

Complex sidebars example

Here's an complete example with complex sidebar usage:

sidebars.json
{
  "mySidebar": [
    {
      "Editing docs": [
        "editing-docs/docs-components",
        {
          "type": "autogenerated",
          "dirName": "Managing docs"
        }
      ]
    },
    {
      "type": "autogenerated",
      "dirName": "Overview"
    },
    {
      "type": "link",
      "label": "Learn more",
      "href": "https://example.com"
    }
  ]
}
1
Copied!