Skip to content

Chicago Docs

Menus

Overview

This section describes how to create your site's main menu (the menu that appears in the header) and how to add docs to the sidebar navigation menu.

Both the main menu and the sidebar menu(s) are specified in the @kabartolo/gatsby-theme-chicago-docs options in the gatsby-config.js file for your site.

The main menu is the menu that appears in the header. In your gatsby-config.js theme options, add an an array of objects called mainMenu. Each object should have a name and path.

Omit this field if you don't want a main menu for your site.

site/gatsby-config.js

JavaScript
module.exports = {
  plugins: [
    {
      resolve: '@kabartolo/gatsby-theme-chicago-docs',
      options: {
        menus: {
          mainMenu: [
            {
              name: 'Home',
              path: '/',
            },
            {
              name: 'Docs',
              path: '/docs/',
            },
            {
              name: 'Tutorials',
              path: '/tutorials/',
            },
          ],
        },
      },
    },
  ],
}

The sidebar menu lists the files that make up your project's documentation. This list is displayed in the sidebar, but it is also used on each doc page to create the breadcrumb links and the links to previous and next docs.

When displayed in the sidebar, the menu can organize doc files into groups (i.e., accordions) that can be expanded and collapsed. This helps make it easy to navigate your docs.

By default, single posts are also displayed as accordions that expand to show part of their table of contents. To disable this, set sidebarAllowTOC to false in the theme options. Also by default, multiple accordions can be open at the same time. You can disable this by setting sidebarAllowMultipleOpen to false (then only one accordion will be open at a time).

You can also change the nested accordion depth with sidebarDepth (default: 3) in the theme options. This is the total depth including groups and table of contents.

To create a sidebar menu, add an array called sidebarMenus to the gatsby-config.js options. This array is a list of objects with the following properties:

sidebarMenus properties

  • name

    optional    string
    default: '' (empty string)

    Used in the breadcrumb link (e.g., 'Tutorials'). This breadcrumb link will not appear if name is omitted.

  • sidebarLabel

    optional    string
    default: value of name

    Label appearing in the sidebar header (e.g., 'Tutorials'). Useful when there are multiple sidebar menus. If omitted, uses the value of the name field. If set to '' (empty string), the sidebar header will not render.

  • dropdownLabel

    optional    string
    default: value of name

    Label appearing in the dropdown docs menu on mobile (e.g., 'Menu'). If omitted, uses the value of the name field. If set to '' (empty string), no label will appear.

  • slug

    optional    string
    default: '' (empty string)

    The directory within docsPath containing the docs for this menu (e.g., 'tutorials' for src/docs/tutorials).

  • items

    optional    string

    List of docs in custom order to be displayed in the menu. If omitted, the sidebar will be populated automatically from the slug directory. However, nested groups must contain an index.mdx file to be created automatically.

Directory structure for example below

src
└── docs
     └──tutorials
        ├── jekyll
        │   ├── how-to-install-plugins.mdx
        │   ├── jekyll-quick-start.mdx
        │   ├── index.mdx
        ├── gatsby
        |   ├── gatsby-quick-start.mdx
        │   ├── how-to-install-plugins.mdx
        │   ├── index.mdx
        ├── how-to-write-tutorials.mdx
        └── index.mdx

site/gatsby-config.js

JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
module.exports = {
  plugins: [
    {
      resolve: '@kabartolo/gatsby-theme-chicago-docs',
      options: {
        sidebarMenus: [
          {
            name: 'Tutorials',
            slug: 'tutorials',
            dropdownLabel: 'Menu',
            items: [
              // see example below
            ],
          }, 
        ],
      },  
    },
  ],
}

Each item in the items list can have the following properties:

Item properties

  • name

    optional    string
    default: value of frontmatter shortTitle or title

    Label for the doc or group of docs in the sidebar (e.g., 'Gatsby Tutorials'). Also used in the breadcrumb link for this part of the path. For an automatically created group, this name defaults to the shortTitle or title of its index.mdx.

  • slug

    required    string

    Slug for a single doc (e.g., 'how-to-write-tutorials') or the directory for a group of docs (e.g., 'jekyll').

  • isGroup

    optional    boolean
    default: false

    Whether this item represents a directory of docs.

  • items

    optional    object[]
    default: all docs in slug directory

    List of docs in custom order to be displayed in the menu. If omitted, all docs in this directory are added automatically.

Directory structure for example below

src
└── docs
     └──tutorials
        ├── jekyll
        │   ├── how-to-install-plugins.mdx
        │   ├── jekyll-quick-start.mdx
        │   ├── index.mdx
        ├── gatsby
        |   ├── gatsby-quick-start.mdx
        │   ├── how-to-install-plugins.mdx
        │   ├── index.mdx
        ├── how-to-write-tutorials.mdx
        └── index.mdx

site/gatsby-config.js

JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
module.exports = {
  plugins: [
    {
      resolve: '@kabartolo/gatsby-theme-chicago-docs',
      options: {
        sidebarMenus: [
          {
            name: 'Tutorials',
            dropdownLabel: 'Menu',
            items: [
              {
                slug: 'how-to-write-tutorials',
              }
              {
                name: 'Jekyll Tutorials',
                slug: 'jekyll',
                isGroup: true,
                // items in custom order
                items: [
                  {
                    slug: 'jekyll-quick-start',
                  },
                  {
                    slug: 'how-to-install-plugins',
                  },
                ],
              },
              {
                name: 'Gatsby Tutorials',
                slug: 'gatsby',
                isGroup: true,
                // items in folder added automatically
              },
            ],
          }, 
        ],
      },  
    },
  ],
}

Multiple Sidebar Menus

You can define multiple sidebar menus for different parts of your site, grouped according to the base path of the docs (e.g., /tutorials).

In this example, the first sidebar menu will appear for any docs with a base path of /documentation (e.g., example.com/docs/documentation/gatsby/mdx-guide, while the second will appear for any docs with a base path of /tutorials (e.g., example.com/docs/tutorials/how-to-write-tutorials):

src
├───docs
    ├── documentation
    │   ├── gatsby
    │   │   ├── index.mdx
    │   │   ├── mdx-guide.mdx
    │   │   ├── quick-start.mdx
    │   ├── index.mdx
    │   ├── overview.mdx
    └── tutorials
        ├── jekyll
        │   ├── how-to-install-plugins.mdx
        │   ├── jekyll-quick-start.mdx
        │   ├── index.mdx
        ├── gatsby
        |   ├── gatsby-quick-start.mdx
        │   ├── how-to-install-plugins.mdx
        │   ├── index.mdx
        ├── how-to-write-tutorials.mdx
        └── index.mdx

site/gatsby-config.js

JavaScript
module.exports = {
  plugins: [
    {
      resolve: '@kabartolo/gatsby-theme-chicago-docs',
      options: {
        sidebarMenus: [
          {
            name: 'Documentation',
            slug: 'documentation',
            items: [
              {
                slug: 'overview',
              },
              {
                name: 'Usage with Gatsby',
                slug: 'gatsby',
                isGroup: true,
                // items in folder added automatically
              },
            ],
          },
          {
            name: 'Tutorials',
            slug: 'tutorials',
            items: [
              {
                slug: 'how-to-write-tutorials',
              }
              {
                name: 'Jekyll Tutorials',
                slug: 'jekyll',
                isGroup: true,
                // items in custom order
                items: [
                  {
                    slug: 'jekyll-quick-start',
                  },
                  {
                    slug: 'how-to-install-plugins',
                  },
                ],
              },
              {
                name: 'Gatsby Tutorials',
                slug: 'gatsby',
                isGroup: true,
                // items in folder added automatically
              },
            ],
          },
        },
      },
    },
  ],
}
©2020 K. A. BartoloGatsby theme: Chicago Docs