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" | string
      Required
      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
            string
            Required
            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
          string
          Required
          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
          string
          Required
          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
              string
              Required
              The URL the page serves at.
              source
              string
              Required
              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.
              collapsed
              boolean
              Fold this group behind a toggle on its header: it starts collapsed and opens on a click, or when it holds the active page (like the rest of the sidebar's open state, it starts over on the next page). Only meaningful for a TOP-LEVEL group — a nested group starts collapsed anyway (see `expanded` ). The generated API reference sets it on its objects group ( `api.openapi[..].options.objectsCollapsed` ).
              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
                  string
                  Required
                  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.
          collapsed
          boolean
          Fold this group behind a toggle on its header: it starts collapsed and opens on a click, or when it holds the active page (like the rest of the sidebar's open state, it starts over on the next page). Only meaningful for a TOP-LEVEL group — a nested group starts collapsed anyway (see `expanded` ). The generated API reference sets it on its objects group ( `api.openapi[..].options.objectsCollapsed` ).
          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 NavigationItem
            Required
            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 NavigationItem
            Required
            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
            string
            Required
            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 NavigationItem
        Required
        Core interface for navigation items
          title
          string
          The navigation item title
          description
          string
          The navigation item description
          page
          string
          The navigation page, if set it redirects to the page + matches based on routing
          href
          string
          The navigation href, if set it redirects but does not match based on routing
          icon
          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 NavigationItem
              Required
              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 NavigationItem
                Required
                Core interface for navigation items
                  title
                  string
                  The navigation item title
                  description
                  string
                  The navigation item description
                  page