xyd 0.1.0-beta - Coming Soon

/
Reference
/
Settings

Settings

Main settings interface for the application

Properties

  • theme
    Theme
    Theme configuration for the application
    • name
      "poetry" | "cosmo" | "opener" | "picasso" | "gusto" | "solar" | "terrarium" | stringRequired
      A theme name.
    • logo
      Path to logo image or object with path to "light" and "dark" mode logo images, and where the logo links to.
      • Logo
        Logo
        Logo configuration interface
        • light
          string

          Path to the logo in light mode. For example: /path/to/logo.svg

        • dark
          string

          Path to the logo in dark mode. For example: /path/to/logo.svg

        • alt
          string

          Alternative text for the logo image. The logo is the only content of the link to the home page, so this doubles as that link's accessible name. Defaults to seo.metatags["og:site_name"] , then to "Home" .

        • href
          string
          External href to when clicking on the logo
        • page
          string
          The page to link to when clicking on the logo
      • string
        string
      • React.JSX.Element
        React.JSX.Element
    • fonts
      ThemeFont
      Font configuration for the theme.
      • Font
        Font
        • family
          string
          The font family to use.
        • weight
          string
          The font weight to use.
        • src
          string
          The font src to use.
        • format
          "woff2" | "woff" | "ttf"
          The font format to use.
      • Font[]
        Font[]
    • favicon
      string
      Path to the favicon image. For example: /path/to/favicon.svg
    • icons
      Icons
      The iconify library setup.
      • library
        The iconify library
        • IconLibrary
          IconLibrary
          • name
            stringRequired
            The iconify library name
          • version
            string
            The iconify library version
          • default
            boolean
            The default iconify icon name
          • noprefix
            boolean
            Merge icons from the library into the default iconify library
        • string
          string
        • IconLibrary[]
          IconLibrary[]
    • appearance
      Appearance
      Appearance configuration for the theme.
      • colorScheme
        "light" | "dark" | "os"
        The default color scheme to use.
      • colorSchemeButton

        If false then the color scheme button will not be displayed.

      • colors
        Colors
        Colors configuration for the theme.
        • primary
          stringRequired
          The primary color of the theme.
        • light
          string
          The light color of the theme.
        • dark
          string
          The dark color of the theme.
      • cssTokens
        CSS tokens for the theme.
      • presets
        string[]
        Presets for the theme.
      • logo
        AppearanceLogo
        Logo appearance for the theme.
        • sidebar
          boolean | "mobile" | "desktop"

          If true then the logo will be displayed on the sidebar.

        • header
          boolean | "mobile" | "desktop"

          If true then the logo will be displayed on the header.

      • search
        AppearanceSearch
        Search appearance for the theme.
        • fullWidth
          boolean

          If true then the search bar will be displayed as a full width.

        • sidebar
          boolean | "mobile" | "desktop"

          If true then the search bar will be displayed on the sidebar.

        • middle
          boolean | "mobile" | "desktop"

          If true then the search bar will be displayed in the middle of the header.

        • right
          boolean | "mobile" | "desktop"

          If true then the search bar will be displayed on the right side of the header.

      • header
        AppearanceHeader
        Header appearance for the theme.
        • externalArrow
          boolean

          If true then the header external links will display an external arrow.

        • separator
          "right"

          If right then separator will be displayed on the right side of the header.

        • type
          "classic" | "pad"
          The type of the header.
        • buttonSize
          "sm" | "md" | "lg"
          The button size of the header.
      • tabs
        AppearanceTabs
        Tabs appearance for the theme.
        • surface
          "center" | "sidebar"
          The tabs to display in the header.
      • sidebar
        AppearanceSidebar
        Sidebar appearance for the theme.
        • externalArrow
          boolean

          If true then the sidebar will display a scroll shadow.

        • scrollShadow
          boolean

          If true then the sidebar will display a scroll shadow.

        • scrollbar
          "secondary"
          The color of the sidebar scrollbar.
        • scrollbarColor
          string
          The color of the sidebar scrollbar.
        • scrollTransition
          "smooth" | "instant"
          The transition behaviour of the sidebar scroll when navigating to a new page.
        • groupCase
          "none" | "uppercase"

          Letter-casing of sidebar group headers. Defaults to "uppercase" ; set

          "none" to render group labels exactly as authored.

        • scroll
          "sidebar" | "list"

          Which element scrolls. "list" (default): only the item list scrolls, below the fixed (pinned) region. "sidebar" : the WHOLE sidebar scrolls — the scrollbar spans its full height — and the fixed region sticks to the top while items scroll beneath it.

      • buttons
        AppearanceButtons
        Buttons appearance for the theme.
        • rounded
          boolean | "sm" | "md" | "lg"
      • tables
        AppearanceTables
        Table appearance for the theme.
        • kind
          "secondary"
          The kind of the table.
      • banner
        AppearanceBanner
        Banner appearance for the theme.
        • fixed
          boolean

          If true then the banner will have fixed position (always visible).

      • content
        AppearanceContent
        Content appearance for the theme.
        • contentDecorator
          "secondary"
          Content decorator for the theme.
        • breadcrumbs

          Controls the breadcrumbs. true / false toggles them; an object ( AppearanceBreadcrumbs ) additionally configures links and

          rootLevel (both default true ).

          • AppearanceBreadcrumbs
            AppearanceBreadcrumbs
            Fine-grained breadcrumbs options (the object form of AppearanceContent.breadcrumbs ).
            • links
              boolean

              If true (default) breadcrumb items that resolve to a real route render as clickable links; if false every crumb is plain text.

            • rootLevel
              boolean

              If true (default) the top-level segment (the tab/route the page belongs to, e.g. "Guides") is included; if false it is omitted.

          • boolean
            boolean
        • sectionSeparator
          boolean

          If true then the section separator will be displayed.

      • footer
        AppearanceFooter
        Footer appearance for the theme.
        • surface
          "page"
          The footer surface.
      • navigationDropdown
        AppearanceNavigationDropdown

        Navigation dropdown appearance (header anchors & tabs dropdownMenu ).

        • chevron
          "rotate" | "static"

          Trigger chevron behavior when the menu is open. "rotate" (default) flips the chevron; "static" leaves it unchanged.

        • items
          "padded" | "flush"

          Menu item layout. "flush" makes the hovered item background touch all four edges of the popover (no surrounding padding); "padded" (default) keeps a small inset with rounded item corners.

    • writer
      Writer
      Writer configuration for the theme.
      • maxTocDepth
        number
        The maximum number of table of conten§ts levels.
      • copyPage
        boolean
        Copy page button
    • coder
      Coder
      Coder configuration for the theme, including options like syntax highlighting.
      • lines
        boolean

        If true then code blocks will have line numbers by default.

      • scroll
        boolean

        If true then code blocks will have a scrollbar by default.

      • syntaxHighlight
        Theme
        Syntax highlighting configuration.
    • head
      array of HeadConfig [string, Record<string, string | boolean>, ]
      Configuration type for head elements that can be added to the HTML head. Format: [tagName, attributes, content] @example: ['script', { src: 'https://example.com/script.js', defer: true }]
    • scripts
      string[]
      Custom scripts to be added to the head of the every page. Paths are relative to the root of the project or absolute.
  • navigation
    Navigation
    Navigation configuration
    • sidebar
      array of SidebarNavigation
      Sidebar navigation type
      • SidebarRoute
        SidebarRoute
        Sidebar route configuration
        • route
          stringRequired
          Route for this sidebar
        • group
          string
          The group of the route
        • id
          string
          The id of the route
        • pages
          Required
          Sidebar pages within this route or sub routes
      • Sidebar
        Sidebar
        Sidebar configuration
        • group
          string
          The name of the group
        • page
          string
          Makes the group itself a real page (the "Group Page" feature). When set, the group resolves to this route — so it becomes a clickable breadcrumb automatically. (Clickable group headers in the sidebar are still Coming Soon.)
        • title
          string
          Label for a `{ page, title }` entry — a page reference with no `group` and no `pages` . It overrides the page's frontmatter title, and is the only way to label a route that has no markdown behind it, such as a generated API reference: without it the sidebar row renders blank.
        • pages
          array of PageURL
          Page URL type
          • SourcePage
            SourcePage
            A page whose URL differs from its markdown file path. Sugar for the VirtualPage object form — normalized at boot ( `{ page, source }` → `{ virtual: source, page }` ), so the whole engine only ever sees the virtual shape. Use it when several files should share a URL scheme, e.g. per-framework variants: ```json { "page": "docs/angular/logs", "source": "docs/logs.angular" } { "page": "docs/bun/logs", "source": "docs/logs.bun" } ```
            • page
              stringRequired
              The URL the page serves at.
            • source
              stringRequired
              The markdown file path, extension-less — like a string page entry ( `docs/logs.angular` → `docs/logs.angular.md` / `.mdx` ).
            • title
              string
              Optional sidebar label override.
            • contextControls
              ContextControls
              Page context controls for THIS page (replaces the global set).
          • Sidebar
            Sidebar
            Sidebar configuration
            • group
              string
              The name of the group
            • page
              string
              Makes the group itself a real page (the "Group Page" feature). When set, the group resolves to this route — so it becomes a clickable breadcrumb automatically. (Clickable group headers in the sidebar are still Coming Soon.)
            • title
              string
              Label for a `{ page, title }` entry — a page reference with no `group` and no `pages` . It overrides the page's frontmatter title, and is the only way to label a route that has no markdown behind it, such as a generated API reference: without it the sidebar row renders blank.
            • pages
              array of PageURL
              The relative paths to the markdown files that will serve as pages. Note: groups are recursive, so to add a sub-folder add another group object in the page array.
            • icon
              string
              The icon of the group.
            • expanded
              boolean
              Open this group on load, even when the reader is on a page outside it. Sets the INITIAL state only — it is a default, not a lock: the group still opens by itself when it holds the active page, and a reader who collapses it keeps it collapsed for as long as they stay on the page (like the rest of the sidebar's open state, it starts over on the next one). Only meaningful for a nested group — top-level groups are always open.
            • order
              Order
              The order of the group.
            • asToc
              Treat this group's pages as a table of contents instead of real pages. Their markdown files are NOT routable (no routes, no prerender) — the content of every page is injected as a section into the enclosing route's index page, sidebar items scroll to those sections (with scroll-spy active marking), and the right-hand TOC is hidden on that composed page. `true` enables it with defaults; the object form tunes behaviors (all default to enabled).
              • SidebarAsTocOptions
                SidebarAsTocOptions
                Behavior options for an `asToc` sidebar group (the object form). Every option defaults to `true` — `asToc: true` ≡ `asToc: {}` .
                • indicator
                  boolean
                  TOC-style visual indicator on the group's sidebar items (the vertical track line the right-hand TOC uses). Default `true` .
                • breadcrumbs
                  boolean
                  Breadcrumbs on the composed host page that follow the section being read (group name / section title, updated by scroll). Default `true` .
              • boolean
                boolean
          • ComponentPage
            ComponentPage
            A custom React component rendered AS a sidebar item. `component` is a path (relative to the docs project, e.g. `"./components/TryNewVersion"` ) to a module whose DEFAULT export is a function component. It renders inside the framework context, so it may use `@xyd-js/framework/react` hooks; `props` are passed to it. `fixed: true` pins it in the sidebar's fixed region (above the scrollable list).
            • fixed
              boolean
              Pin this item in the sidebar's fixed region (stays visible on scroll).
            • component
              Required
              A path to a default-export React component (relative to the docs project), or an object with that path under `import` plus `props` for the component.
              • 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
          • string
            string
          • VirtualPage
            VirtualPage
        • icon
          string
          The icon of the group.
        • expanded
          boolean
          Open this group on load, even when the reader is on a page outside it. Sets the INITIAL state only — it is a default, not a lock: the group still opens by itself when it holds the active page, and a reader who collapses it keeps it collapsed for as long as they stay on the page (like the rest of the sidebar's open state, it starts over on the next one). Only meaningful for a nested group — top-level groups are always open.
        • order
          Order
          The order of the group.
        • asToc
          Treat this group's pages as a table of contents instead of real pages. Their markdown files are NOT routable (no routes, no prerender) — the content of every page is injected as a section into the enclosing route's index page, sidebar items scroll to those sections (with scroll-spy active marking), and the right-hand TOC is hidden on that composed page. `true` enables it with defaults; the object form tunes behaviors (all default to enabled).
          • SidebarAsTocOptions
            SidebarAsTocOptions
            Behavior options for an `asToc` sidebar group (the object form). Every option defaults to `true` — `asToc: true` ≡ `asToc: {}` .
            • indicator
              boolean
              TOC-style visual indicator on the group's sidebar items (the vertical track line the right-hand TOC uses). Default `true` .
            • breadcrumbs
              boolean
              Breadcrumbs on the composed host page that follow the section being read (group name / section title, updated by scroll). Default `true` .
          • boolean
            boolean
      • string
        string
    • tabs
      array of Tabs NavigationItem
      Tabs configuration
      • 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"` .
    • sidebarDropdown
      array of SidebarDropdown NavigationItem
      Sidebar dropdown navigation - navigation through dropdown in the sidebar.
      • 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"` .
    • segments
      array of Segment
      Segment configuration
      • 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"` .
    • anchors
      Anchors
      Anchors navigation - fixed navigation, for anchor-like elements.
      • 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
    • languages
      array of LanguageNavigation
      Per-locale navigation block. Same shape as `Navigation` plus locale fields.
      • language
        stringRequired
        ISO 639-1 code for this locale. Used in URLs ( `/{language}/...` ).
      • name
        string
        Native display name shown in the locale switcher ( `Polski` , not `Polish` ).
      • default
        boolean
        Marks this entry as the default locale (URLs unprefixed). Ignored when `i18n.defaultLocale` is set explicitly. If neither is set, the first entry wins.
      • dir
        "ltr" | "rtl"
        Text direction. Sets `<html dir>` on pages of this locale. Defaults to `"ltr"` .
      • overrides
        Partial<Settings>
        Per-locale overrides for top-level `Settings` keys (e.g. `components.footer` , `theme.head` , `seo` ). Shallow-merged on top of root settings when serving this locale. If you override `components.footer` , the whole footer config is replaced for this locale.
      • sidebar
        array of SidebarNavigation
        Sidebar navigation type
        • SidebarRoute
          SidebarRoute
          Sidebar route configuration
          • route
            stringRequired
            Route for this sidebar
          • group
            string
            The group of the route
          • id
            string
            The id of the route
          • pages
            Required
            Sidebar pages within this route or sub routes
        • Sidebar
          Sidebar
          Sidebar configuration
          • group
            string
            The name of the group
          • page
            string
            Makes the group itself a real page (the "Group Page" feature). When set, the group resolves to this route — so it becomes a clickable breadcrumb automatically. (Clickable group headers in the sidebar are still Coming Soon.)
          • title
            string
            Label for a `{ page, title }` entry — a page reference with no `group` and no `pages` . It overrides the page's frontmatter title, and is the only way to label a route that has no markdown behind it, such as a generated API reference: without it the sidebar row renders blank.
          • pages
            array of PageURL
            Page URL type
            • SourcePage
              SourcePage
              A page whose URL differs from its markdown file path. Sugar for the VirtualPage object form — normalized at boot ( `{ page, source }` → `{ virtual: source, page }` ), so the whole engine only ever sees the virtual shape. Use it when several files should share a URL scheme, e.g. per-framework variants: ```json { "page": "docs/angular/logs", "source": "docs/logs.angular" } { "page": "docs/bun/logs", "source": "docs/logs.bun" } ```
              • page
                stringRequired
                The URL the page serves at.
              • source
                stringRequired
                The markdown file path, extension-less — like a string page entry ( `docs/logs.angular` → `docs/logs.angular.md` / `.mdx` ).
              • title
                string
                Optional sidebar label override.
              • contextControls
                ContextControls
                Page context controls for THIS page (replaces the global set).
            • Sidebar
              Sidebar
              Sidebar configuration
              • group
                string
                The name of the group
              • page
                string
                Makes the group itself a real page (the "Group Page" feature). When set, the group resolves to this route — so it becomes a clickable breadcrumb automatically. (Clickable group headers in the sidebar are still Coming Soon.)
              • title
                string
                Label for a `{ page, title }` entry — a page reference with no `group` and no `pages` . It overrides the page's frontmatter title, and is the only way to label a route that has no markdown behind it, such as a generated API reference: without it the sidebar row renders blank.
              • pages
                array of PageURL
                The relative paths to the markdown files that will serve as pages. Note: groups are recursive, so to add a sub-folder add another group object in the page array.
              • icon
                string
                The icon of the group.
              • expanded
                boolean
                Open this group on load, even when the reader is on a page outside it. Sets the INITIAL state only — it is a default, not a lock: the group still opens by itself when it holds the active page, and a reader who collapses it keeps it collapsed for as long as they stay on the page (like the rest of the sidebar's open state, it starts over on the next one). Only meaningful for a nested group — top-level groups are always open.
              • order
                Order
                The order of the group.
              • asToc
                Treat this group's pages as a table of contents instead of real pages. Their markdown files are NOT routable (no routes, no prerender) — the content of every page is injected as a section into the enclosing route's index page, sidebar items scroll to those sections (with scroll-spy active marking), and the right-hand TOC is hidden on that composed page. `true` enables it with defaults; the object form tunes behaviors (all default to enabled).
                • SidebarAsTocOptions
                  SidebarAsTocOptions
                  Behavior options for an `asToc` sidebar group (the object form). Every option defaults to `true` — `asToc: true` ≡ `asToc: {}` .
                  • indicator
                    boolean
                    TOC-style visual indicator on the group's sidebar items (the vertical track line the right-hand TOC uses). Default `true` .
                  • breadcrumbs
                    boolean
                    Breadcrumbs on the composed host page that follow the section being read (group name / section title, updated by scroll). Default `true` .
                • boolean
                  boolean
            • ComponentPage
              ComponentPage
              A custom React component rendered AS a sidebar item. `component` is a path (relative to the docs project, e.g. `"./components/TryNewVersion"` ) to a module whose DEFAULT export is a function component. It renders inside the framework context, so it may use `@xyd-js/framework/react` hooks; `props` are passed to it. `fixed: true` pins it in the sidebar's fixed region (above the scrollable list).
              • fixed
                boolean
                Pin this item in the sidebar's fixed region (stays visible on scroll).
              • component
                Required
                A path to a default-export React component (relative to the docs project), or an object with that path under `import` plus `props` for the component.
                • 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
            • string
              string
            • VirtualPage
              VirtualPage
          • icon
            string
            The icon of the group.
          • expanded
            boolean
            Open this group on load, even when the reader is on a page outside it. Sets the INITIAL state only — it is a default, not a lock: the group still opens by itself when it holds the active page, and a reader who collapses it keeps it collapsed for as long as they stay on the page (like the rest of the sidebar's open state, it starts over on the next one). Only meaningful for a nested group — top-level groups are always open.
          • order
            Order
            The order of the group.
          • asToc
            Treat this group's pages as a table of contents instead of real pages. Their markdown files are NOT routable (no routes, no prerender) — the content of every page is injected as a section into the enclosing route's index page, sidebar items scroll to those sections (with scroll-spy active marking), and the right-hand TOC is hidden on that composed page. `true` enables it with defaults; the object form tunes behaviors (all default to enabled).
            • SidebarAsTocOptions
              SidebarAsTocOptions
              Behavior options for an `asToc` sidebar group (the object form). Every option defaults to `true` — `asToc: true` ≡ `asToc: {}` .
              • indicator
                boolean
                TOC-style visual indicator on the group's sidebar items (the vertical track line the right-hand TOC uses). Default `true` .
              • breadcrumbs
                boolean
                Breadcrumbs on the composed host page that follow the section being read (group name / section title, updated by scroll). Default `true` .
            • boolean
              boolean
        • string
          string
      • tabs
        array of Tabs NavigationItem
        Tabs configuration
        • 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"` .
      • sidebarDropdown
        array of SidebarDropdown NavigationItem
        Sidebar dropdown for this locale.
        • 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"` .
      • segments
        array of Segment
        Segment configuration
        • 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"` .
      • anchors
        Anchors
        Anchors for this locale.
        • 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
  • api
    API
    API Docs configuration
    • openapi
      APIFile
      API file configuration. Can be a path, an array of paths, a map of paths, or an advanced configuration
      • APIFileMap
        API file map type
      • APIFileAdvanced
        APIFileAdvanced
        API file advanced type
        • source
          stringRequired
          Source configuration
        • route
          string
          Route configuration
        • info
          APIInfo
          API information configuration
          • baseUrl
            string
            The base url for all API endpoints. If baseUrl is an array, it will enable for multiple base url options that the user can toggle.
          • auth
            APIAuth
            Authentication information
            • method
              "bearer" | "basic" | "key"Required
              The authentication strategy used for all API endpoints
          • name
            string
            The name of the authentication parameter used in the API playground. If method is basic, the format should be [usernameName]:[passwordName]
          • inputPrefix
            string
            The default value that's designed to be a prefisx for the authentication input field. E.g. If an inputPrefix of AuthKey would inherit the default input result of the authentication field as AuthKey.
          • request
            APIInfoRequest
            Request configuration
            • example
              Configurations for the auto-generated API request examples
              • languages
                string[]
                An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing x-codeSamples or use our default languages which include bash, python, javascript, php, go, java
        • options
          APIFileOptions
          Preset-specific rendering options (e.g. CLI).
          • globalOptionsPerCommand
            boolean
            (CLI) Render the CLI's global options on every command page. When `false` (the default), the global options are rendered once as a dedicated "Global options" page in the sidebar instead of repeated on each command.
        • sdk
          "go" | "python" | "typescript" | "ruby" | "java" | "csharp" | boolean
          SDK-native reference docs (OpenAPI sources only). Generates per-language SDK types, method signatures, and usage samples at BUILD time via the OpenSDK toolchain, with the raw-HTTP (cURL) view kept as a first-class entry in the page-wide language switcher. `true` enables all languages; the object form restricts them. Ignored for graphql/cli/mcp sources.
      • string
        string
      • string[]
        string[]
    • graphql
      APIFile
      API file configuration. Can be a path, an array of paths, a map of paths, or an advanced configuration
      • APIFileMap
        API file map type
      • APIFileAdvanced
        APIFileAdvanced
        API file advanced type
        • source
          stringRequired
          Source configuration
        • route
          string
          Route configuration
        • info
          APIInfo
          API information configuration
          • baseUrl
            string
            The base url for all API endpoints. If baseUrl is an array, it will enable for multiple base url options that the user can toggle.
          • auth
            APIAuth
            Authentication information
            • method
              "bearer" | "basic" | "key"Required
              The authentication strategy used for all API endpoints
          • name
            string
            The name of the authentication parameter used in the API playground. If method is basic, the format should be [usernameName]:[passwordName]
          • inputPrefix
            string
            The default value that's designed to be a prefisx for the authentication input field. E.g. If an inputPrefix of AuthKey would inherit the default input result of the authentication field as AuthKey.
          • request
            APIInfoRequest
            Request configuration
            • example
              Configurations for the auto-generated API request examples
              • languages
                string[]
                An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing x-codeSamples or use our default languages which include bash, python, javascript, php, go, java
        • options
          APIFileOptions
          Preset-specific rendering options (e.g. CLI).
          • globalOptionsPerCommand
            boolean
            (CLI) Render the CLI's global options on every command page. When `false` (the default), the global options are rendered once as a dedicated "Global options" page in the sidebar instead of repeated on each command.
        • sdk
          "go" | "python" | "typescript" | "ruby" | "java" | "csharp" | boolean
          SDK-native reference docs (OpenAPI sources only). Generates per-language SDK types, method signatures, and usage samples at BUILD time via the OpenSDK toolchain, with the raw-HTTP (cURL) view kept as a first-class entry in the page-wide language switcher. `true` enables all languages; the object form restricts them. Ignored for graphql/cli/mcp sources.
      • string
        string
      • string[]
        string[]
    • sources
      APIFile
      API file configuration. Can be a path, an array of paths, a map of paths, or an advanced configuration
      • APIFileMap
        API file map type
      • APIFileAdvanced
        APIFileAdvanced
        API file advanced type
        • source
          stringRequired
          Source configuration
        • route
          string
          Route configuration
        • info
          APIInfo
          API information configuration
          • baseUrl
            string
            The base url for all API endpoints. If baseUrl is an array, it will enable for multiple base url options that the user can toggle.
          • auth
            APIAuth
            Authentication information
            • method
              "bearer" | "basic" | "key"Required
              The authentication strategy used for all API endpoints
          • name
            string
            The name of the authentication parameter used in the API playground. If method is basic, the format should be [usernameName]:[passwordName]
          • inputPrefix
            string
            The default value that's designed to be a prefisx for the authentication input field. E.g. If an inputPrefix of AuthKey would inherit the default input result of the authentication field as AuthKey.
          • request
            APIInfoRequest
            Request configuration
            • example
              Configurations for the auto-generated API request examples
              • languages
                string[]
                An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing x-codeSamples or use our default languages which include bash, python, javascript, php, go, java
        • options
          APIFileOptions
          Preset-specific rendering options (e.g. CLI).
          • globalOptionsPerCommand
            boolean
            (CLI) Render the CLI's global options on every command page. When `false` (the default), the global options are rendered once as a dedicated "Global options" page in the sidebar instead of repeated on each command.
        • sdk
          "go" | "python" | "typescript" | "ruby" | "java" | "csharp" | boolean
          SDK-native reference docs (OpenAPI sources only). Generates per-language SDK types, method signatures, and usage samples at BUILD time via the OpenSDK toolchain, with the raw-HTTP (cURL) view kept as a first-class entry in the page-wide language switcher. `true` enables all languages; the object form restricts them. Ignored for graphql/cli/mcp sources.
      • string
        string
      • string[]
        string[]
    • mcp
      MCPAPIFile
      MCP API file configuration. URL shorthand, advanced, or named map.
      • MCPAPIFileAdvanced
        MCPAPIFileAdvanced
        • source
          stringRequired
          MCP server URL (http/https/sse).
        • route
          string
          Sidebar route prefix to nest the generated pages under.
        • info
          MCPAPIInfo
          Per-source options.
          • name
            string
            Display name for the server in the docs.
          • token
            string
            Bearer token sent as `Authorization: Bearer <token>` . Supports `$ENV_VAR` substitution via the standard settings env replacement.
          • headers
            Record<string, string>
            Additional request headers (e.g. cookies, custom API keys).
      • string
        string
      • MCPAPIFileAdvanced[]
        MCPAPIFileAdvanced[]
      • $$union
    • cli
      APIFile
      API file configuration. Can be a path, an array of paths, a map of paths, or an advanced configuration
      • APIFileMap
        API file map type
      • APIFileAdvanced
        APIFileAdvanced
        API file advanced type
        • source
          stringRequired
          Source configuration
        • route
          string
          Route configuration
        • info
          APIInfo
          API information configuration
          • baseUrl
            string
            The base url for all API endpoints. If baseUrl is an array, it will enable for multiple base url options that the user can toggle.
          • auth
            APIAuth
            Authentication information
            • method
              "bearer" | "basic" | "key"Required
              The authentication strategy used for all API endpoints
          • name
            string
            The name of the authentication parameter used in the API playground. If method is basic, the format should be [usernameName]:[passwordName]
          • inputPrefix
            string
            The default value that's designed to be a prefisx for the authentication input field. E.g. If an inputPrefix of AuthKey would inherit the default input result of the authentication field as AuthKey.
          • request
            APIInfoRequest
            Request configuration
            • example
              Configurations for the auto-generated API request examples
              • languages
                string[]
                An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing x-codeSamples or use our default languages which include bash, python, javascript, php, go, java
        • options
          APIFileOptions
          Preset-specific rendering options (e.g. CLI).
          • globalOptionsPerCommand
            boolean
            (CLI) Render the CLI's global options on every command page. When `false` (the default), the global options are rendered once as a dedicated "Global options" page in the sidebar instead of repeated on each command.
        • sdk
          "go" | "python" | "typescript" | "ruby" | "java" | "csharp" | boolean
          SDK-native reference docs (OpenAPI sources only). Generates per-language SDK types, method signatures, and usage samples at BUILD time via the OpenSDK toolchain, with the raw-HTTP (cURL) view kept as a first-class entry in the page-wide language switcher. `true` enables all languages; the object form restricts them. Ignored for graphql/cli/mcp sources.
      • string
        string
      • string[]
        string[]
  • integrations
    Integrations
    Integrations configuration
    • analytics
      IntegrationAnalytics
      Configurations to add third-party analytics integrations. See full list of supported analytics here.
      • livesession
        IntegrationAnalyticsLiveSession
        LiveSession analytics configuration
        • trackId
          stringRequired
          LiveSession's TrackID
    • support
      IntegrationSupport
      Configurations to add third-party support integrations.
      • chatwoot
        IntegrationSupportChatwoot
        Chatwoot support configuration
        • websiteToken
          stringRequired
          Chatwoot website token
        • baseURL
          string
          Chatwoot base URL
        • chatwootSettings
          JSON
          Chatwoot settings
      • intercom
        IntegrationSupportIntercom
        Intercom support configuration
        • appId
          stringRequired
          Intercom app ID
        • apiBase
          string
          Intercom API base
      • livechat
        IntegrationSupportLivechat
        Livechat support configuration
        • licenseId
          stringRequired
          Livechat license ID
    • search
      IntegrationSearch
      Configurations to add third-party search integrations. See full list of supported search here.
      • algolia
        Algolia search configuration
        • appId
          stringRequired
          Algolia application ID
        • apiKey
          stringRequired
          Algolia API key
      • orama
        boolean
    • abtesting
      IntegrationABTesting
      A/B testing configuration
      • contextMaxAge
        number
        Context max age in milliseconds
      • contextStorageKey
        string
        Context storage key used to store the context in the browser storage
      • providers
        IntegrationABTestingProviders
        Providers configuration
        • growthbook
          IntegrationABTestingGrowthBook
          GrowthBook configuration
          • apiHost
            stringRequired
            GrowthBook API host
          • clientKey
            stringRequired
            GrowthBook client key
        • launchdarkly
          IntegrationABTestingLaunchDarkly
          LaunchDarkly configuration
          • env
            stringRequired
            LaunchDarkly environment key
    • diagrams
      Diagrams configuration
      • DiagramsConfig
        DiagramsConfig
        Diagrams configuration object
        • mermaid
          "img-png" | "img-svg" | "inline-svg" | "pre-mermaid" | boolean

          Mermaid diagram configuration

          true : Enable with default settings

          : Enable with custom settings

        • graphviz

          Graphviz diagram configuration

          true : Enable with default settings

          : Enable with custom settings

        • .config
          Detailed diagram config, useful for e.g setting diagram's interactive.
          • interactive
            boolean
      • boolean
        boolean
      • DiagramType[]
        DiagramType[]
    • editLink
      EditLink
      Edit link configuration
      • baseUrl
        stringRequired
        The base URL for the edit link
      • title
        string
        The title for the edit link
      • icon
        string
        The icon for the edit link
    • .apps
      AppsDirectory
      Custom apps directory.
      • githubStar
        IntegrationAppGithubStar
        Github star app configuration.
        • title
          stringRequired
          The title of the Github button
        • label
          string
          The label of the Github Button
        • href
          stringRequired
          The href of the Github project
        • dataShowCount
          boolean
          The data-show-count of the Github project
        • dataIcon
          string
          The data-icon of the Github button
        • dataSize
          string
          The data-size of the Github button
        • ariaLabel
          string
          The aria-label of the Github button
      • supademo
        IntegrationAppSupademo
        Supademo app configuration.
        • apiKey
          stringRequired
          The Supademo API key
  • plugins
    array of Plugins
    Plugin configuration
    • PluginConfig
      [PluginName, PluginArgs[]]
    • string
      string
  • seo
    SEO
    SEO configuration
    • domain
      string
      Domain name
    • metatags
      Meta tags
  • ai
    AI
    AI configuration
    • llmsTxt
      LLMs txt configuration
      • LLMsTxt
        LLMsTxt
        LLMs txt configuration
        • title
          stringRequired
          Title of the LLMs txt
        • baseUrl
          stringRequired
          Base URL of the LLMs txt
        • summary
          string
          Description of the LLMs txt
        • sections
          Sections of the LLMs txt
      • string
        string
  • advanced
    Advanced
    Advanced configuration
    • basename
      string

      Mount the site under a URL prefix, e.g. "/docs" or "/docs" .

      Every route, raw file ( llms.txt , the .md twins) and asset URL carries the prefix, and xyd build writes the whole site under

      .xyd/build/client/<basename>/ — a self-contained tree to serve at that path. The Vite base defaults to <basename>/ ; set advanced.vite.base

      to serve the assets from somewhere else.

    • vite
      UserConfig
      Custom Vite configuration overrides. Merged with xyd's internal Vite config.
  • components
    Components
    Components configuration
    • banner
      WebEditorBanner
      WebEditor banner configuration
      • content
        ComponentLike Required
        A type that can be used to represent a component-like structure.
        • JSONComponent
          JSONComponent
          JSON representation of a component.
          • component
            stringRequired
            The component type, e.g. "Button", "Card", etc.
          • props
            Record<string, any>
            The component's children, which can be a string, an array of strings, or an array of JSONComponent objects.
        • React.JSX.Element
          React.JSX.Element
        • string
          string
      • label
        string
        Banner label.
      • kind
        "secondary"
        Banner kind.
      • href
        string
        Banner href.
      • icon
        string
        Banner icon.
    • contextControls
      ContextControls

      Global page context controls — contextual page actions (copy page, view markdown, ChatGPT/Claude, MCP), a content-version switcher, dropdown grouping, or custom components — rendered on every page at their appearance slot ( header | toc-top | toc-bottom ). A page can override or opt out via frontmatter contextControls: or its sidebar entry ( ).

    • footer
      WebEditorFooter
      WebEditor footer configuration
      • kind
        "minimal"
      • logo
        • ComponentLike
          ComponentLike
          A type that can be used to represent a component-like structure.
          • JSONComponent
            JSONComponent
            JSON representation of a component.
            • component
              stringRequired
              The component type, e.g. "Button", "Card", etc.
            • props
              Record<string, any>
              The component's children, which can be a string, an array of strings, or an array of JSONComponent objects.
          • React.JSX.Element
            React.JSX.Element
          • string
            string
        • boolean
          boolean
      • social
        Footer socials
        • x
          string
        • facebook
          string
        • youtube
          string
        • discord
          string
        • slack
          string
        • github
          string
        • linkedin
          string
        • instagram
          string
        • hackernews
          string
        • medium
          string
        • telegram
          string
        • bluesky
          string
        • reddit
          string
      • links
        WebEditorFooterLinks
        Footer links
      • footnote
        ComponentLike
        A type that can be used to represent a component-like structure.
        • JSONComponent
          JSONComponent
          JSON representation of a component.
          • component
            stringRequired
            The component type, e.g. "Button", "Card", etc.
          • props
            Record<string, any>
            The component's children, which can be a string, an array of strings, or an array of JSONComponent objects.
        • React.JSX.Element
          React.JSX.Element
        • string
          string
    • filterSidebar

      Built-in "filter sidebar" input that narrows the sidebar tree to matching items. It renders in the sidebar's fixed (pinned) region. true uses the default placeholder; pass a FilterSidebar object to customize the placeholder and scope it to specific routes.

      • FilterSidebar
        FilterSidebar

        Configuration for the built-in sidebar filter input ( components.filterSidebar ).

        • placeholder
          string

          Placeholder text for the filter input. Defaults to "Filter sidebar" .

        • routes
          string[]

          Render the filter ONLY on pages whose route is under one of these prefixes (e.g. ["terraform/language"] ). A page matches when its slug starts with a listed prefix. Omit (or leave empty) to show the filter on every page.

      • boolean
        boolean
  • engine
    Engine
    Engine configuration - advanced engine-like configuration
    • paths
      Path aliases for imports. Avoid long relative paths by creating shortcuts.
    • uniform
      EngineUniform
      Uniform configuration
      • store
        boolean

        If true then virtual pages will not created and generated content will be stored on disk

  • accessControl
    AccessControl
    Access control configuration. Enables page-level access control on documentation sites. Protected page content is never included in HTML source -- it is code-split into separate JS chunks loaded only after authentication.
    • provider
      Required
      Authentication provider configuration
      • AccessControlProviderOAuth
        AccessControlProviderOAuth
        • type
          "oauth"Required
        • authorizationUrl
          stringRequired
          OAuth 2.0 authorization URL
        • tokenUrl
          stringRequired
          OAuth 2.0 token endpoint URL
        • clientId
          stringRequired
          OAuth 2.0 client ID. Use $ENV_VAR syntax for secrets.
        • scopes
          string[]
          OAuth 2.0 scopes to request
        • callbackPath
          string
          Callback path for OAuth redirect.
        • userInfoUrl
          string
          URL to fetch user info after auth (provides groups)
        • groupsClaim
          string
          Field in user info response containing groups/roles
      • AccessControlProviderJWT
        AccessControlProviderJWT
        • type
          "jwt"Required
        • loginUrl
          stringRequired
          URL to redirect unauthenticated users for login
        • callbackPath
          string
          Callback path where JWT is delivered via hash fragment.
        • algorithm
          "EdDSA" | "RS256" | "HS256"
          JWT signing algorithm.
        • jwksUrl
          string
          JWKS URL for key verification (EdDSA/RS256)
        • secret
          string
          Shared secret for HS256 verification. Use $ENV_VAR syntax.
        • groupsClaim
          string
          JWT claim name containing user groups/roles
      • AccessControlProviderCustom
        AccessControlProviderCustom
        • type
          "custom"Required
        • handler
          stringRequired
          Path to custom auth handler module
    • defaultAccess
      "public" | "protected"
      Default access level for all pages. "protected" = all pages require auth unless marked public. "public" = all pages are public unless marked protected.
    • rules
      array of AccessControlRule
      Pattern-based access rules, evaluated in order. First match wins.
      • match
        stringRequired
        Glob pattern matching page paths
      • access
        "public" | "protected"Required
        Access level for matched pages
      • groups
        string[]
        Groups allowed access (only for "protected" access)
    • login

      Login page configuration.

      • String: path to a custom component (e.g., "./my-login.tsx"). The component receives useAccessControl() context automatically.
      • Object: configuration for the built-in login page.
      • AccessControlLoginConfig
        AccessControlLoginConfig
        • page
          string
          Custom login page (path to mdx file)
        • logo
          string
          Logo to display on the default login page
        • title
          string
          Title text on the login page
        • description
          string
          Description text on the login page
        • backgroundImage
          string
          Background image URL for the login page
      • string
        string
    • unauthorizedBehavior
      "redirect" | "404"
      Behavior when user is unauthorized. "redirect" sends to login page. "404" shows not-found page (hides existence of protected page).
    • deploy
      AccessControlDeployConfig
      Deployment platform for server-side content protection
      • platform
        "netlify-edge" | "vercel-edge" | "cloudflare-edge" | "node-edge"Required
        Target deployment platform
    • session
      AccessControlSessionConfig
      Session/token configuration
      • maxAge
        number
        Session duration in seconds.
      • cookieName
        string
        Cookie/storage key name.
  • i18n
    I18nConfig

    Internationalization (i18n) configuration.

    The required source of truth for i18n is navigation.languages[] . This i18n block is OPTIONAL and carries only site-wide flags (explicit defaultLocale override, browser detection, translation catalogs).

    If navigation.languages[] is absent, this block has no effect.

    • defaultLocale
      string

      Explicit default locale. Overrides any default: true shorthand on

      navigation.languages[] entries when set. Must match a language declared in navigation.languages[] .

    • detectLanguage
      boolean

      When true , redirect / based on navigator.language / xyd-locale

      cookie. Default false .

    • catalogs
      Record<string, string | TranslationCatalog>

      Translation catalogs for "i18n: <key>" references in component config. Either a path to a JSON file, or an inline catalog object, keyed by locale code. If omitted, the framework auto-discovers

      i18n/.json files at the project root.

Built with

Show your support! Star us on GitHub ⭐️