Navigation

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.

Sidebar

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

Groups

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

Nested Groups

You can also define nested groups:

Group PageComing Soon

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

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:

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:

Tabs

Navigation Item structure displayed in tabs-like style:

Sidebar Dropdown

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

Anchors

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

Dropdown MenuComing Soon

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".

SegmentsExperimental

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:

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:

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

File-Convention RoutingComing Soon

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:

The generated HTML pages will be:

index.md

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