Navigation

Core concepts

Navigation

Learn how to navigate your docs

Navigation is one of the core concepts in xyd to understand as it determines how your documentation pages are organized, navigated, and accessed by users. It provides flexible ways to structure your content.

Overview

You can customize the navigation by adding a routes in docs.json file to your project.

The navigation property controls the hierarchy of your documentation. It's grouped into multiple properties:

sidebar - Main navigation, usually displayed on the left side where all pages are rendered.
tabs - Navigate through tabs, the most in header area.
sidebarDropdown - Navigate through sidebar dropdown.
anchors - Fixed navigation, helpful for displaying a static navigation/links.
segments - Smaller navigational structures based on specific route.

Dividing a navigation into multiple properties helps you to organize your documentation better.

asset

The simples way to define sidebar is declaring a pages within it:

{
  "navigation": {
    "sidebar": [
      "overview", // overview.md
      "quickstart", // quickstart.md
      "guides/introduction" // guides/introduction.md
    ]
  }
}

Important

Each entry of the pages MUST be a path to a file that exists within your docs.

Note you do not need to append .md/.mdx or / at beginning to the file paths.

Groups

If you need more advanced structures, define sidebar as object:


{
  "sidebar": [
    {
+
      "group": "Get Started",
      "icon": "code",
      "pages": [
          "docs/guides/introduction",
          "docs/guides/getting-started",
          "docs/guides/deploy"
      ]
    }
    // ... other groups
  ]
}

Tip

Group shows on the sidebar above the sidebar items.

Nested Groups

You can also define nested groups:


{
  "sidebar": [
    {
      "group": "Get Started",
      "pages": [
          "docs/guides/introduction",
          "docs/guides/getting-started",
+
          {
            "group": "Deployment",
            "pages": [
              "docs/guides/deploy/overview",
              "docs/guides/deploy/netlify"
            ]
          }
      ]
    }
    // ... other groups
  ]
}

Reference

Check the reference of Sidebar.

Group PageComing Soon

If you want to have a clickable group as a page, define page instead of group:


{
  "sidebar": [
    {
      "group": "Integrations",
      "pages": [
          {
-
              "group": "Integrations",
+
              "page": "docs/guides/integrations",
              "icon": "chart-line",
              "pages": [
                  "docs/guides/integrations/analytics/analytics-integrations",
                  "docs/guides/integrations/analytics/livesession"
              ]
          }
      ]
    }
    // ... other groups
  ]
}

Tip

The sidebar title comes from a Page Meta.

Routing

You can also do more advanced routing in the sidebar, like matching based on the specific route:


{
    "sidebar": [
        {
+
            "route": "docs",
            "pages": [
                {
                    "group": "Getting Started",
                    "pages": [
                       "docs/introduction",
                       "docs/components"
                    ]
                },
                {
                    // ...
                }
            ]
        },
        {
+
            "route": "docs/api",
            "pages": [
                {
                    "group": "API",
                    "pages": [
                        "docs/api/introduction",
                        "docs/api/error-handling"
                    ]
                }
            ]
        }
    ]
}

Tip

This approach gives you more control over the routing and allows you to create more complex navigation structures.

Order

Thanks to order you are able to set a custom order of docs groups. It's the most useful with auto-generatated docs - for OpenAPI/GraphQL integration for example. There are a few options how to change an order:


{
  "navigation": {
      "sidebar": [
            {
                "route": "api/rest",
                "pages": [
                    {
                        "group": "API & Reference",
                        "order": 0,
                        "pages": [
                            "api/rest/introduction"
                        ]
                    },
                    ...
                ]
            }
      ]
  }
}

Info

Check out how it can be used for API Docs here.

Tabs

Navigation Item structure displayed in tabs-like style:

{
  "navigation": {
    "tabs": [
      {
          "title": "Guides",
          "page": "docs",
          "icon": "book"
      },
      {
          "title": "Components",
          "page": "docs/components",
          "icon": "component"
      },
      {
          "title": "Reference",
          "page": "docs/reference",
          "icon": "brackets"
      }
    ]
  }
}

Tabs API Reference

Check the full Tabs API Reference

array of NavigationItem
Core interface for navigation items
- title
  string
  The navigation item title
- description
  string
  The navigation item description
- page
  string
  The navigation page, if set it redirects to the page + matches based on routing
- href
  string
  The navigation href, if set it redirects but does not match based on routing
- icon
  any
  The navigation item icon

Sidebar Dropdown

Navigation Item structure displayed in dropdown-like style inside sidebar:

{
  "navigation": {
    "sidebarDropdown": [
      {
          "title": "Guides",
          "page": "docs",
          "icon": "book"
      },
      {
          "title": "Components",
          "page": "docs/components",
          "icon": "component"
      },
      {
          "title": "Reference",
          "page": "docs/reference",
          "icon": "brackets"
      }
    ]
  }
}

Sidebar Dropdown API Reference

Check the full Sidebar Dropdown API Reference

array of NavigationItem
Core interface for navigation items
- title
  string
  The navigation item title
- description
  string
  The navigation item description
- page
  string
  The navigation page, if set it redirects to the page + matches based on routing
- href
  string
  The navigation href, if set it redirects but does not match based on routing
- icon
  any
  The navigation item icon

Anchors

asset

Anchors provide a way to add fixed navigation elements. They're useful for displaying important external links or resources.


{
  "navigation": {
    "anchors": {
+
      "header": [
          {
              "title": "Public Roadmap",
              "href": "https://github.com/orgs/livesession/projects/4"
          },
          {
              "title": "Feedback",
              "href": "https://github.com/livesession/xyd/discussions",
              "button": "primary"
          },
          {
              "title": "Github",
              "href": "https://github.com/livesession/xyd/discussions",
              "icon": "lucide:github" // use your custom icons
          },
           {
              "title": "Slack",
              "href": "http://xyd-docs.slack.com",
              "social": "slack" // use pre-defined social icons
          }
      ]
    }
  }
}


{
  "navigation": {
    "anchors": {
+
      "sidebar": {
+
        "bottom": [
          {
            "href": "https://docs.example.com",
            "icon": "icon-book",
            "title": "Documentation"
          },
          {
            "href": "https://community.example.com",
            "icon": "icon-users",
            "title": "Community"
          },
          {
            "href": "https://github.com/example",
            "icon": "icon-code",
            "title": "GitHub"
          },
          {
            "href": "https://support.example.com",
            "icon": "icon-chat",
            "title": "Support"
          }
        ]
      }
    }
  }
}

Anchors API Reference

Check the full Anchors API Reference

header
array of AnchorHeader
Header anchors
- NavigationItem
  NavigationItem
  Core interface for navigation items
  title
  string
  The navigation item title
  description
  string
  The navigation item description
  page
  string
  The navigation page, if set it redirects to the page + matches based on routing
  href
  string
  The navigation href, if set it redirects but does not match based on routing
  icon
  any
  The navigation item icon
- NavigationItemButton
  NavigationItemButton
  NavigationItem
  NavigationItem
  Core interface for navigation items
  title
  string
  The navigation item title
  description
  string
  The navigation item description
  page
  string
  The navigation page, if set it redirects to the page + matches based on routing
  href
  string
  The navigation href, if set it redirects but does not match based on routing
  icon
  any
  The navigation item icon
  NavigationItem & { button: "primary"
  NavigationItem & { button: "primary"
  "secondary"; }
  "secondary"; }
- NavigationItemSocial
  NavigationItemSocial
  NavigationItem
  NavigationItem
  Core interface for navigation items
  title
  string
  The navigation item title
  description
  string
  The navigation item description
  page
  string
  The navigation page, if set it redirects to the page + matches based on routing
  href
  string
  The navigation href, if set it redirects but does not match based on routing
  icon
  any
  The navigation item icon
  NavigationItem & { social: Social; }
  NavigationItem & { social: Social; }
sidebar
{ top?: NavigationItem[]; bottom?: NavigationItem[]; }
Sidebar anchors
- top
  array of NavigationItem
- bottom
  array of NavigationItem

SegmentsExperimental

asset

Segments allows you to create smaller navigational structures based on specific route. Thanks to that you can create for example a subheader that will shown only on specific route:


{
  "navigation": {
+
    "segments": [
      {
+
        "route": "docs/api",
        "title": "API",
        "appearance": "sidebarDropdown",
        "pages": [
          {
            "title": "Getting Started",
            "page": "docs/api"
          },
          {
            "title": "Authentication",
            "page": "docs/api/auth"
          },
        ]
      },
      {
+
        "route": "docs/guides",
        "title": "Guides",
        "pages": [
          {
            "title": "Quick Start",
            "page": "docs/guides/quickstart"
          },
          {
            "title": "Tutorials",
            "page": "docs/guides/tutorials"
          }
        ]
      }
    ]
  }
}

Tip

Check out how to create a subheader using segments here.

Segments API Reference

Check the full Segment API Reference

route
string
Required
Route for this segment
title
string
Title of this segment
appearance
"sidebarDropdown"
Appearance of this segment. If 'sidebarDropdown' then show this segment as a dropdown in the sidebar if match.
pages
array of NavigationItem
Required
Core interface for navigation items
- title
  string
  The navigation item title
- description
  string
  The navigation item description
- page
  string
  The navigation page, if set it redirects to the page + matches based on routing
- href
  string
  The navigation href, if set it redirects but does not match based on routing
- icon
  any
  The navigation item icon

File-Convention RoutingComing Soon

File-convention routing is powerful because you don't need any configuration but also has some limitations.
If you need more control over the routing, you need to use the settings based routing instead.

Using file-convention routing means the generated HTML pages are mapped from the directory structure of the source Markdown files.

For example, given the following directory structure:

.
├ docs
│  └─ index.md
│  └─ quickstart.md
|
├─ index.md
├─ faq.md
|
└─ settings.json

The generated HTML pages will be:

index.md                  --> /index.html (accessible as /)
faq.md                    --> /faq.html
docs/index.md             --> /docs/index.html (accessible as /docs/)
docs/quickstart.md        --> /docs/quickstart.html

index.md

If you crate an index.md file at root of your documentation project, xyd will serve that content as index page.

Pages Special Symbols