Update Navigation

[ntotten]

The current state of the navigation configuration is split into three different areas of the configuration which makes it somewhat difficult to think through it. The user needs to understand that various id references point to sidebar items, etc.

I think we can simplify this by instead using a single navigation configuration that is a tree with explicit references. With this change the id object always references from the navigation configuration out to another thing - a document, an api, or whatever we have in the future. Each "type" can reference its own id.

{
  navigation: {
    tabs: {
      [
        { label: "Home", type: "doc", id: "index" },
        {
          label: "Documentation",
          link: "/docs/overview",
          sidebar: [
            { type: "doc", label: "Overview", id: "docs/overview" },
            {
              type: "category",
              label: "Subcategory",
              items: ["docs/example", "docs/other-example"],
            },
          ],
        },
        {
          type: "api-reference",
          id: "my-api",
        },
      ];
    }
  }
}

The above configuration would render the following tabs

• Home (links to the docs /index), there is no sidebar since there are no children
• Documentation (opens the /docs/overview page), this has a sidebar
• API Reference (opens the api at /my-api

A few other notes:

• ids should always be fully namespaced. If a document is in /pages/docs/example, the id would be docs/example
• Labels should always come from the content if not explictly set, this means the doc title or sidebar_label or in the case of an API it would be the api name as defined in the openapi spec

[linear]

ZUP-3539 Update Navigation

The current state of the navigation configuration is split into three different areas of the configuration which makes it somewhat difficult to think through it. The user needs to understand that various id references point to sidebar items, etc.

I think we can simplify this by instead using a single navigation configuration that is a tree with explicit references. With this change the id object always references from the navigation configuration out to another thing - a document, an api, or whatever we have in the future. Each "type" can reference its own id.

{
  navigation: {
    tabs: {
      [
        { label: "Home", type: "doc", id: "index" },
        {
          label: "Documentation",
          link: "/docs/overview",
          sidebar: [
            { type: "doc", label: "Overview", id: "docs/overview" },
            {
              type: "category",
              label: "Subcategory",
              items: ["docs/example", "docs/other-example"],
            },
          ],
        },
        {
          type: "api-reference",
          id: "my-api",
        },
      ];
    }
  }
}

The above configuration would render the following tabs

• Home (links to the docs /index), there is no sidebar since there are no children
• Documentation (opens the /docs/overview page), this has a sidebar
• API Reference (opens the api at /my-api

A few other notes:

• ids should always be fully namespaced. If a document is in /pages/docs/example, the id would be docs/example
• Labels should always come from the content if not explictly set, this means the doc title or sidebar_label or in the case of an API it would be the api name as defined in the openapi spec

[ntotten]

So I was playing around with using Zudoku on the zuplo docs site and one thing that I ran into was I realized just how tied together the top nav and the sidebar are to the URLs in the path. Additionally how the topnav is tied to the file system locations of the docs. I think these are both mistakes. If there is one thing I have learned in my years of managing many docs sites is that sidebar navigation and product categorization needs to be separate of UI - concretely, URLs should essentially be immutable regardless of how the sidebar navigation or top level navigation is laid out. We are going to change those a lot, but if we have to move files around on the file system and change URLs it is going to make it very hard to do so.

I think we need to change the following:

1. The sidebar should be able to be composed up of any doc, regardless of its ___location on in the file system
2. The top navigation should not impact the URL by default. Current the id of the topNavigation is the first section of the path. This means that the folder structure of docs must match the top nav.
3. Docs should always be referenced by their full id - which is the path of the document relative to the root ___location of the pages. So if you have pages/my/example.md the id MUST always be my/example when it is set in the sidebar. The id is NEVER composed of multiple part (i.e. topNav ID + doc ID).

This will mean that it is possible to put documents in multiple sidebars which will make it so that we cannot know definitely which is the current sidebar. We will probably just have to pick the first sidebar the document is in. I think docusaurus also has this issue. I think this is a small tradeoff in order to keep the URLs and file system locations of articles static even when your navigation structure changes.