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.

Even while the clickable group header in the sidebar is still Coming Soon, a group that declares a page (either a Group Page, or a named group with a page) already becomes a clickable breadcrumb automatically — breadcrumbs link any crumb that resolves to a real route. See breadcrumb links.

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
  React.ReactNode
  The navigation item icon
- color
  string
  Accent color (any CSS color) for this item. Used by `logoTrailing` product switchers and accent-aware themes (e.g. `terrarium` ) to recolor the UI per product — the active item's `color` is applied as `--theme-color-primary` .
- dropdownMenu
  Nested navigation rendered as a dropdown menu under this item. Recursive — a child may itself declare `dropdownMenu` to create submenus (e.g. `api → [Browser SDK, REST API, GraphQL]` ). Supported on header anchors and tabs. Accepts a plain item array, or the object form DropdownMenu carrying menu-level options (e.g. `{ itemsPerColumn: 7, items: [...] }` ).
  DropdownMenu
  DropdownMenu
  Object form of NavigationItem.dropdownMenu : the menu items plus menu-level options.
  items
  array of NavigationItemRequired
  The menu items.
  itemsPerColumn
  number
  Maximum items rendered in ONE COLUMN — overflowing items wrap into additional columns (e.g. `7` renders a 12-item menu as two columns of 7 + 5). Omit for a single column.
  NavigationItem[]
  NavigationItem[]
- float
  "center" | "right"
  Render this item on the RIGHT of the header rather than with its siblings, before the search box — for a tab that is a reference you look things up in rather than a stop in the reading order (e.g. an API reference). Honored only by the `tabs` appearance, and there only for `"right"` — the union matches WebEditorHeader , which intersects this type and already carries both values. The item keeps everything a centered tab has, including `dropdownMenu` and route-prefix active highlighting.
- pages
  array of NavigationItem
  Nested navigation items — recursive. Honored ONLY by sidebar-dropdown surfaces ( `navigation.sidebarDropdown` and `appearance: "sidebarDropdown"` segments): an entry with `pages` (typically without `page` / `href` ) renders as an inline-expandable GROUP row inside the dropdown popover — clicking it expands its children (indented) within the same popover. `title` , `icon` , and `description` apply to the group row. Other appearances (tabs, logoTrailing) ignore nesting.
- trigger
  "hover" | "click"
  How the `dropdownMenu` opens. Defaults to `"hover"` .

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
  React.ReactNode
  The navigation item icon
- color
  string
  Accent color (any CSS color) for this item. Used by `logoTrailing` product switchers and accent-aware themes (e.g. `terrarium` ) to recolor the UI per product — the active item's `color` is applied as `--theme-color-primary` .
- dropdownMenu
  Nested navigation rendered as a dropdown menu under this item. Recursive — a child may itself declare `dropdownMenu` to create submenus (e.g. `api → [Browser SDK, REST API, GraphQL]` ). Supported on header anchors and tabs. Accepts a plain item array, or the object form DropdownMenu carrying menu-level options (e.g. `{ itemsPerColumn: 7, items: [...] }` ).
  DropdownMenu
  DropdownMenu
  Object form of NavigationItem.dropdownMenu : the menu items plus menu-level options.
  items
  array of NavigationItemRequired
  The menu items.
  itemsPerColumn
  number
  Maximum items rendered in ONE COLUMN — overflowing items wrap into additional columns (e.g. `7` renders a 12-item menu as two columns of 7 + 5). Omit for a single column.
  NavigationItem[]
  NavigationItem[]
- float
  "center" | "right"
  Render this item on the RIGHT of the header rather than with its siblings, before the search box — for a tab that is a reference you look things up in rather than a stop in the reading order (e.g. an API reference). Honored only by the `tabs` appearance, and there only for `"right"` — the union matches WebEditorHeader , which intersects this type and already carries both values. The item keeps everything a centered tab has, including `dropdownMenu` and route-prefix active highlighting.
- pages
  array of NavigationItem
  Nested navigation items — recursive. Honored ONLY by sidebar-dropdown surfaces ( `navigation.sidebarDropdown` and `appearance: "sidebarDropdown"` segments): an entry with `pages` (typically without `page` / `href` ) renders as an inline-expandable GROUP row inside the dropdown popover — clicking it expands its children (indented) within the same popover. `title` , `icon` , and `description` apply to the group row. Other appearances (tabs, logoTrailing) ignore nesting.
- trigger
  "hover" | "click"
  How the `dropdownMenu` opens. Defaults to `"hover"` .

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
  React.ReactNode
  The navigation item icon
  color
  string
  Accent color (any CSS color) for this item. Used by `logoTrailing` product switchers and accent-aware themes (e.g. `terrarium` ) to recolor the UI per product — the active item's `color` is applied as `--theme-color-primary` .
  dropdownMenu
  Nested navigation rendered as a dropdown menu under this item. Recursive — a child may itself declare `dropdownMenu` to create submenus (e.g. `api → [Browser SDK, REST API, GraphQL]` ). Supported on header anchors and tabs. Accepts a plain item array, or the object form DropdownMenu carrying menu-level options (e.g. `{ itemsPerColumn: 7, items: [...] }` ).
  DropdownMenu
  DropdownMenu
  Object form of NavigationItem.dropdownMenu : the menu items plus menu-level options.
  items
  array of NavigationItemRequired
  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
  React.ReactNode
  The navigation item icon
  color
  string
  Accent color (any CSS color) for this item. Used by `logoTrailing` product switchers and accent-aware themes (e.g. `terrarium` ) to recolor the UI per product — the active item's `color` is applied as `--theme-color-primary` .
  dropdownMenu
  Nested navigation rendered as a dropdown menu under this item. Recursive — a child may itself declare `dropdownMenu` to create submenus (e.g. `api → [Browser SDK, REST API, GraphQL]` ). Supported on header anchors and tabs. Accepts a plain item array, or the object form DropdownMenu carrying menu-level options (e.g. `{ itemsPerColumn: 7, items: [...] }` ).
  DropdownMenu
  DropdownMenu
  Object form of NavigationItem.dropdownMenu : the menu items plus menu-level options.
  items
  array of NavigationItemRequired
  The menu items.
  itemsPerColumn
  number
  Maximum items rendered in ONE COLUMN — overflowing items wrap into additional columns (e.g. `7` renders a 12-item menu as two columns of 7 + 5). Omit for a single column.
  NavigationItem[]
  NavigationItem[]
  float
  "center" | "right"
  Render this item on the RIGHT of the header rather than with its siblings, before the search box — for a tab that is a reference you look things up in rather than a stop in the reading order (e.g. an API reference). Honored only by the `tabs` appearance, and there only for `"right"` — the union matches WebEditorHeader , which intersects this type and already carries both values. The item keeps everything a centered tab has, including `dropdownMenu` and route-prefix active highlighting.
  pages
  array of NavigationItem
  Nested navigation items — recursive. Honored ONLY by sidebar-dropdown surfaces ( `navigation.sidebarDropdown` and `appearance: "sidebarDropdown"` segments): an entry with `pages` (typically without `page` / `href` ) renders as an inline-expandable GROUP row inside the dropdown popover — clicking it expands its children (indented) within the same popover. `title` , `icon` , and `description` apply to the group row. Other appearances (tabs, logoTrailing) ignore nesting.
  trigger
  "hover" | "click"
  How the `dropdownMenu` opens. Defaults to `"hover"` .
  itemsPerColumn
  number
  Maximum items rendered in ONE COLUMN — overflowing items wrap into additional columns (e.g. `7` renders a 12-item menu as two columns of 7 + 5). Omit for a single column.
  NavigationItem[]
  NavigationItem[]
  float
  "center" | "right"
  Render this item on the RIGHT of the header rather than with its siblings, before the search box — for a tab that is a reference you look things up in rather than a stop in the reading order (e.g. an API reference). Honored only by the `tabs` appearance, and there only for `"right"` — the union matches WebEditorHeader , which intersects this type and already carries both values. The item keeps everything a centered tab has, including `dropdownMenu` and route-prefix active highlighting.
  pages
  array of NavigationItem
  Nested navigation items — recursive. Honored ONLY by sidebar-dropdown surfaces ( `navigation.sidebarDropdown` and `appearance: "sidebarDropdown"` segments): an entry with `pages` (typically without `page` / `href` ) renders as an inline-expandable GROUP row inside the dropdown popover — clicking it expands its children (indented) within the same popover. `title` , `icon` , and `description` apply to the group row. Other appearances (tabs, logoTrailing) ignore nesting.
  trigger
  "hover" | "click"
  How the `dropdownMenu` opens. Defaults to `"hover"` .
- NavigationItemButton
  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
  React.ReactNode
  The navigation item icon
  color
  string
  Accent color (any CSS color) for this item. Used by `logoTrailing` product switchers and accent-aware themes (e.g. `terrarium` ) to recolor the UI per product — the active item's `color` is applied as `--theme-color-primary` .
  dropdownMenu
  Nested navigation rendered as a dropdown menu under this item. Recursive — a child may itself declare `dropdownMenu` to create submenus (e.g. `api → [Browser SDK, REST API, GraphQL]` ). Supported on header anchors and tabs. Accepts a plain item array, or the object form DropdownMenu carrying menu-level options (e.g. `{ itemsPerColumn: 7, items: [...] }` ).
  DropdownMenu
  DropdownMenu
  Object form of NavigationItem.dropdownMenu : the menu items plus menu-level options.
  items
  array of NavigationItemRequired
  The menu items.
  itemsPerColumn
  number
  Maximum items rendered in ONE COLUMN — overflowing items wrap into additional columns (e.g. `7` renders a 12-item menu as two columns of 7 + 5). Omit for a single column.
  NavigationItem[]
  NavigationItem[]
  float
  "center" | "right"
  Render this item on the RIGHT of the header rather than with its siblings, before the search box — for a tab that is a reference you look things up in rather than a stop in the reading order (e.g. an API reference). Honored only by the `tabs` appearance, and there only for `"right"` — the union matches WebEditorHeader , which intersects this type and already carries both values. The item keeps everything a centered tab has, including `dropdownMenu` and route-prefix active highlighting.
  pages
  array of NavigationItem
  Nested navigation items — recursive. Honored ONLY by sidebar-dropdown surfaces ( `navigation.sidebarDropdown` and `appearance: "sidebarDropdown"` segments): an entry with `pages` (typically without `page` / `href` ) renders as an inline-expandable GROUP row inside the dropdown popover — clicking it expands its children (indented) within the same popover. `title` , `icon` , and `description` apply to the group row. Other appearances (tabs, logoTrailing) ignore nesting.
  trigger
  "hover" | "click"
  How the `dropdownMenu` opens. Defaults to `"hover"` .
- NavigationItemSocial
  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
  React.ReactNode
  The navigation item icon
  color
  string
  Accent color (any CSS color) for this item. Used by `logoTrailing` product switchers and accent-aware themes (e.g. `terrarium` ) to recolor the UI per product — the active item's `color` is applied as `--theme-color-primary` .
  dropdownMenu
  Nested navigation rendered as a dropdown menu under this item. Recursive — a child may itself declare `dropdownMenu` to create submenus (e.g. `api → [Browser SDK, REST API, GraphQL]` ). Supported on header anchors and tabs. Accepts a plain item array, or the object form DropdownMenu carrying menu-level options (e.g. `{ itemsPerColumn: 7, items: [...] }` ).
  DropdownMenu
  DropdownMenu
  Object form of NavigationItem.dropdownMenu : the menu items plus menu-level options.
  items
  array of NavigationItemRequired
  The menu items.
  itemsPerColumn
  number
  Maximum items rendered in ONE COLUMN — overflowing items wrap into additional columns (e.g. `7` renders a 12-item menu as two columns of 7 + 5). Omit for a single column.
  NavigationItem[]
  NavigationItem[]
  float
  "center" | "right"
  Render this item on the RIGHT of the header rather than with its siblings, before the search box — for a tab that is a reference you look things up in rather than a stop in the reading order (e.g. an API reference). Honored only by the `tabs` appearance, and there only for `"right"` — the union matches WebEditorHeader , which intersects this type and already carries both values. The item keeps everything a centered tab has, including `dropdownMenu` and route-prefix active highlighting.
  pages
  array of NavigationItem
  Nested navigation items — recursive. Honored ONLY by sidebar-dropdown surfaces ( `navigation.sidebarDropdown` and `appearance: "sidebarDropdown"` segments): an entry with `pages` (typically without `page` / `href` ) renders as an inline-expandable GROUP row inside the dropdown popover — clicking it expands its children (indented) within the same popover. `title` , `icon` , and `description` apply to the group row. Other appearances (tabs, logoTrailing) ignore nesting.
  trigger
  "hover" | "click"
  How the `dropdownMenu` opens. Defaults to `"hover"` .
sidebar
Sidebar anchors
- top
  array of NavigationItem
- bottom
  array of NavigationItem

Turn a header anchor or a tab into a nested menu with dropdownMenu. Each entry is a Navigation Item; an entry that itself declares dropdownMenu becomes a submenu, so menus can nest to multiple levels.

Use trigger to control how the menu opens — "hover" (default) or "click".


{
  "navigation": {
    "anchors": {
      "header": [
        {
+
          "title": "Products",
+
          "trigger": "hover",
+
          "dropdownMenu": [
            {
              "title": "Browser SDK",
              "dropdownMenu": [
                { "title": "Install", "page": "docs/browser/install" },
                { "title": "Methods", "page": "docs/browser/methods" }
              ]
            },
            { "title": "REST API", "page": "docs/rest" },
            { "title": "GraphQL", "page": "docs/graphql" }
          ]
        }
      ]
    }
  }
}


{
  "navigation": {
    "tabs": [
      { "title": "Overview", "page": "overview" },
      {
+
        "title": "API Reference",
+
        "trigger": "hover",
+
        "dropdownMenu": [
          { "title": "Browser SDK", "page": "docs/browser" },
          { "title": "REST API", "page": "docs/rest" },
          { "title": "GraphQL", "page": "docs/graphql" }
        ]
      }
    ]
  }
}

Style the dropdown — chevron rotation, edge-to-edge items, colors — via appearance.navigationDropdown.

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
Route this segment is scoped to. When a **string**, the segment only shows under that route prefix (route-scoped). When **omitted or `false` **, the segment is GLOBAL — always visible (e.g. a top-level product switcher). The globalness comes from the absence of a route, NOT from the `appearance` .
title
string
Title of this segment
appearance
Appearance of this segment — a SegmentAppearance string, or the object form SegmentAppearanceConfig carrying kind-specific options (e.g. `{ kind: "sidebarDropdown", options: { fixed: true } }` ).
- SegmentAppearance
  SegmentAppearance "sidebarDropdown" | "logoTrailing" | "tabs"
  How a matched Segment is presented. - `"sidebarDropdown"` — a click dropdown at the top of the sidebar. - `"logoTrailing"` — a hover product-switcher rendered right after the logo (wherever the active theme places its logo — header or sidebar). The trigger shows the active page's title (falling back to the segment `title` ), and the menu is the segment `pages` with a check on the active one. - `"tabs"` — a horizontal tab bar in the sub-navigation, scoped to the segment's `route` . Each `page` is a section: its `page` (a route prefix) decides which tab is active, and its `href` is the landing page the tab links to. Use one route-scoped `tabs` segment per product to get per-product tab bars (e.g. Documentation / API / CLI).
- SegmentAppearanceConfig
  SegmentAppearanceSidebarDropdown
  `appearance: { kind: "sidebarDropdown", options }`
  kind
  "sidebarDropdown"Required
  options
  fixed
  boolean
  Render the section switcher in the sidebar's FIXED (pinned) region — it stays visible while the item list scrolls. Defaults to `false` (rendered at the top of the scrollable list).
trigger
"hover" | "click"
How a `logoTrailing` segment's dropdown opens. Defaults to `"hover"` .
iconOnly
boolean
`logoTrailing` only: render the trigger ICON-ONLY — show the active item's icon at a larger size and hide the trigger title label. Use when the icon is a full wordmark image (logo + product name) so a text label is redundant. Defaults to `false` .
component
`logoTrailing` only: a custom component rendered AS this segment's dropdown PANEL (e.g. a rich multi-column product mega-menu), instead of the default `pages` list. A path to a default-export React component (relative to the docs project), or `{ import, props }` . Resolved through the same user-components registry as sidebar `ComponentPage` components, so it may use `@xyd-js/framework/react` hooks; the framework also passes it the active item, the segment, and the resolved `items` .
- ComponentPageImport
  ComponentPageImport
  Object form of `ComponentPage.component` : an import path plus optional props.
  import
  stringRequired
  Path to a default-export React component, relative to the docs project.
  props
  Record<string, any>
  Props passed to the component.
- string
  string
pages
array of NavigationItemRequired
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
  React.ReactNode
  The navigation item icon
- color
  string
  Accent color (any CSS color) for this item. Used by `logoTrailing` product switchers and accent-aware themes (e.g. `terrarium` ) to recolor the UI per product — the active item's `color` is applied as `--theme-color-primary` .
- dropdownMenu
  Nested navigation rendered as a dropdown menu under this item. Recursive — a child may itself declare `dropdownMenu` to create submenus (e.g. `api → [Browser SDK, REST API, GraphQL]` ). Supported on header anchors and tabs. Accepts a plain item array, or the object form DropdownMenu carrying menu-level options (e.g. `{ itemsPerColumn: 7, items: [...] }` ).
  DropdownMenu
  DropdownMenu
  Object form of NavigationItem.dropdownMenu : the menu items plus menu-level options.
  items
  array of NavigationItemRequired
  The menu items.
  itemsPerColumn
  number
  Maximum items rendered in ONE COLUMN — overflowing items wrap into additional columns (e.g. `7` renders a 12-item menu as two columns of 7 + 5). Omit for a single column.
  NavigationItem[]
  NavigationItem[]
- float
  "center" | "right"
  Render this item on the RIGHT of the header rather than with its siblings, before the search box — for a tab that is a reference you look things up in rather than a stop in the reading order (e.g. an API reference). Honored only by the `tabs` appearance, and there only for `"right"` — the union matches WebEditorHeader , which intersects this type and already carries both values. The item keeps everything a centered tab has, including `dropdownMenu` and route-prefix active highlighting.
- pages
  array of NavigationItem
  Nested navigation items — recursive. Honored ONLY by sidebar-dropdown surfaces ( `navigation.sidebarDropdown` and `appearance: "sidebarDropdown"` segments): an entry with `pages` (typically without `page` / `href` ) renders as an inline-expandable GROUP row inside the dropdown popover — clicking it expands its children (indented) within the same popover. `title` , `icon` , and `description` apply to the group row. Other appearances (tabs, logoTrailing) ignore nesting.
- trigger
  "hover" | "click"
  How the `dropdownMenu` opens. Defaults to `"hover"` .

Logo TrailingComing Soon

Set a segment's appearance to "logoTrailing" to render it as a product-switcher right after the logo — wherever your theme places the logo (header, or the sidebar like picasso). Unlike sidebarDropdown, it is global: it appears on every page (a top-level switcher), so you can switch products from anywhere — including the landing page. The trigger shows the active product (whichever page prefixes the current route), falling back to the segment title when none is active; the menu switches between the segment pages (the active one is checked).

This suits docs that span multiple products — e.g. a Products switcher over Session Replay and Web Analytics:


{
  "navigation": {
    "segments": [
      {
        "route": "products",
        "title": "Products",
+
        "appearance": "logoTrailing",
+
        "trigger": "hover",
        "pages": [
          { "title": "Session Replay", "page": "products/session-replay" },
          { "title": "Web Analytics", "page": "products/web-analytics" }
        ]
      }
    ]
  }
}

The dropdown opens on trigger: "hover" (default) or "click". A page may itself declare a nested dropdownMenu to add submenus.

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.

Edit page

Pages Special Symbols

Navigation

Overview

Sidebar

Groups

Nested Groups

Group PageComing Soon

Routing

Order

Tabs

Sidebar Dropdown

Anchors

Dropdown MenuComing Soon

SegmentsExperimental

Logo TrailingComing Soon

File-Convention RoutingComing Soon

index.md