Core concepts
/Settings
Settings
Configure the settings for your documentation
The settings file is the central configuration hub for your documentation.
It's available at root of your project inside the docs.json file.
This configuration file controls the look and feel of your documentation, including navigation, themes, integrations and other.
Source code of settings is available here.
Reference
This section contains the full reference for the docs.json file:
themeThemename"poetry" | "cosmo" | "opener" | "picasso" | "gusto" | "solar" | "terrarium" | stringRequiredlogoLogoLogolightstringdarkstringaltstringhrefstringpagestringstringstringReact.JSX.ElementReact.JSX.ElementfontsThemeFontFontFontfamilystringweightstringsrcstringformat"woff2" | "woff" | "ttf"Font[]Font[]faviconstringiconsIconslibraryIconLibraryIconLibrarynamestringRequiredversionstringdefaultbooleannoprefixbooleanstringstringIconLibrary[]IconLibrary[]appearanceAppearancecolorScheme"light" | "dark" | "os"colorSchemeButtoncolorsColorsprimarystringRequiredlightstringdarkstringcssTokenspresetsstring[]logoAppearanceLogosidebarboolean | "mobile" | "desktop"headerboolean | "mobile" | "desktop"searchAppearanceSearchfullWidthbooleansidebarboolean | "mobile" | "desktop"middleboolean | "mobile" | "desktop"rightboolean | "mobile" | "desktop"headerAppearanceHeaderexternalArrowbooleanseparator"right"type"classic" | "pad"buttonSize"sm" | "md" | "lg"tabsAppearanceTabssurface"center" | "sidebar"sidebarAppearanceSidebarexternalArrowbooleanscrollShadowbooleanscrollbar"secondary"scrollbarColorstringscrollTransition"smooth" | "instant"groupCase"none" | "uppercase"scroll"sidebar" | "list"buttonsAppearanceButtonsroundedboolean | "sm" | "md" | "lg"tablesAppearanceTableskind"secondary"bannerAppearanceBannerfixedbooleancontentAppearanceContentcontentDecorator"secondary"breadcrumbsAppearanceBreadcrumbsAppearanceBreadcrumbslinksbooleanrootLevelbooleanbooleanbooleansectionSeparatorbooleanfooterAppearanceFootersurface"page"navigationDropdownAppearanceNavigationDropdownchevron"rotate" | "static"items"padded" | "flush"writerWritermaxTocDepthnumbercopyPagebooleancoderCoderlinesbooleanscrollbooleansyntaxHighlightThemeheadarray of HeadConfig [string, Record<string, string | boolean>, ]scriptsstring[]navigationNavigationsidebararray of SidebarNavigationSidebarRouteSidebarRouteroutestringRequiredgroupstringidstringpagesRequiredSidebarSidebargroupstringpagestringtitlestringpagesarray of PageURLSourcePageSourcePagepagestringRequiredsourcestringRequiredtitlestringcontextControlsContextControlsSidebarSidebargroupstringpagestringtitlestringpagesarray of PageURLiconstringexpandedbooleanorderOrderasTocSidebarAsTocOptionsSidebarAsTocOptionsindicatorbooleanbreadcrumbsbooleanbooleanbooleanComponentPageComponentPagefixedbooleancomponentRequiredComponentPageImportComponentPageImportimportstringRequiredpropsRecord<string, any>stringstringstringstringVirtualPageVirtualPageiconstringexpandedbooleanorderOrderasTocSidebarAsTocOptionsSidebarAsTocOptionsindicatorbooleanbreadcrumbsbooleanbooleanbooleanstringstringtabsarray of Tabs NavigationItemtitlestringdescriptionstringpagestringhrefstringiconReact.ReactNodecolorstringdropdownMenuDropdownMenuDropdownMenuitemsarray of NavigationItemRequireditemsPerColumnnumberNavigationItem[]NavigationItem[]float"center" | "right"pagesarray of NavigationItemtrigger"hover" | "click"sidebarDropdownarray of SidebarDropdown NavigationItemtitlestringdescriptionstringpagestringhrefstringiconReact.ReactNodecolorstringdropdownMenuDropdownMenuDropdownMenuitemsarray of NavigationItemRequireditemsPerColumnnumberNavigationItem[]NavigationItem[]float"center" | "right"pagesarray of NavigationItemtrigger"hover" | "click"segmentsarray of SegmentroutestringtitlestringappearanceSegmentAppearanceSegmentAppearance "sidebarDropdown" | "logoTrailing" | "tabs"SegmentAppearanceConfigSegmentAppearanceSidebarDropdownkind"sidebarDropdown"Requiredoptionsfixedbooleantrigger"hover" | "click"iconOnlybooleancomponentComponentPageImportComponentPageImportimportstringRequiredpropsRecord<string, any>stringstringpagesarray of NavigationItemRequiredtitlestringdescriptionstringpagestringhrefstringiconReact.ReactNodecolorstringdropdownMenuDropdownMenuDropdownMenuitemsarray of NavigationItemRequireditemsPerColumnnumberNavigationItem[]NavigationItem[]float"center" | "right"pagesarray of NavigationItemtrigger"hover" | "click"anchorsAnchorsheaderarray of AnchorHeaderNavigationItemNavigationItemtitlestringdescriptionstringpagestringhrefstringiconReact.ReactNodecolorstringdropdownMenuDropdownMenuDropdownMenuitemsarray of NavigationItemRequiredtitlestringdescriptionstringpagestringhrefstringiconReact.ReactNodecolorstringdropdownMenuDropdownMenuDropdownMenuitemsarray of NavigationItemRequireditemsPerColumnnumberNavigationItem[]NavigationItem[]float"center" | "right"pagesarray of NavigationItemtrigger"hover" | "click"itemsPerColumnnumberNavigationItem[]NavigationItem[]float"center" | "right"pagesarray of NavigationItemtrigger"hover" | "click"NavigationItemButtonNavigationItemtitlestringdescriptionstringpagestringhrefstringiconReact.ReactNodecolorstringdropdownMenuDropdownMenuDropdownMenuitemsarray of NavigationItemRequireditemsPerColumnnumberNavigationItem[]NavigationItem[]float"center" | "right"pagesarray of NavigationItemtrigger"hover" | "click"NavigationItemSocialNavigationItemtitlestringdescriptionstringpagestringhrefstringiconReact.ReactNodecolorstringdropdownMenuDropdownMenuDropdownMenuitemsarray of NavigationItemRequireditemsPerColumnnumberNavigationItem[]NavigationItem[]float"center" | "right"pagesarray of NavigationItemtrigger"hover" | "click"sidebartoparray of NavigationItembottomarray of NavigationItemlanguagesarray of LanguageNavigationlanguagestringRequirednamestringdefaultbooleandir"ltr" | "rtl"overridesPartial<Settings>sidebararray of SidebarNavigationSidebarRouteSidebarRouteroutestringRequiredgroupstringidstringpagesRequiredSidebarSidebargroupstringpagestringtitlestringpagesarray of PageURLSourcePageSourcePagepagestringRequiredsourcestringRequiredtitlestringcontextControlsContextControlsSidebarSidebargroupstringpagestringtitlestringpagesarray of PageURLiconstringexpandedbooleanorderOrderasTocSidebarAsTocOptionsSidebarAsTocOptionsindicatorbooleanbreadcrumbsbooleanbooleanbooleanComponentPageComponentPagefixedbooleancomponentRequiredComponentPageImportComponentPageImportimportstringRequiredpropsRecord<string, any>stringstringstringstringVirtualPageVirtualPageiconstringexpandedbooleanorderOrderasTocSidebarAsTocOptionsSidebarAsTocOptionsindicatorbooleanbreadcrumbsbooleanbooleanbooleanstringstringtabsarray of Tabs NavigationItemtitlestringdescriptionstringpagestringhrefstringiconReact.ReactNodecolorstringdropdownMenuDropdownMenuDropdownMenuitemsarray of NavigationItemRequireditemsPerColumnnumberNavigationItem[]NavigationItem[]float"center" | "right"pagesarray of NavigationItemtrigger"hover" | "click"sidebarDropdownarray of SidebarDropdown NavigationItemtitlestringdescriptionstringpagestringhrefstringiconReact.ReactNodecolorstringdropdownMenuDropdownMenuDropdownMenuitemsarray of NavigationItemRequireditemsPerColumnnumberNavigationItem[]NavigationItem[]float"center" | "right"pagesarray of NavigationItemtrigger"hover" | "click"segmentsarray of SegmentroutestringtitlestringappearanceSegmentAppearanceSegmentAppearance "sidebarDropdown" | "logoTrailing" | "tabs"SegmentAppearanceConfigSegmentAppearanceSidebarDropdownkind"sidebarDropdown"Requiredoptionsfixedbooleantrigger"hover" | "click"iconOnlybooleancomponentComponentPageImportComponentPageImportimportstringRequiredpropsRecord<string, any>stringstringpagesarray of NavigationItemRequiredtitlestringdescriptionstringpagestringhrefstringiconReact.ReactNodecolorstringdropdownMenuDropdownMenuDropdownMenuitemsarray of NavigationItemRequireditemsPerColumnnumberNavigationItem[]NavigationItem[]float"center" | "right"pagesarray of NavigationItemtrigger"hover" | "click"anchorsAnchorsheaderarray of AnchorHeaderNavigationItemNavigationItemtitlestringdescriptionstringpagestringhrefstringiconReact.ReactNodecolorstringdropdownMenuDropdownMenuDropdownMenuitemsarray of NavigationItemRequiredtitlestringdescriptionstringpagestringhrefstringiconReact.ReactNodecolorstringdropdownMenuDropdownMenuDropdownMenuitemsarray of NavigationItemRequireditemsPerColumnnumberNavigationItem[]NavigationItem[]float"center" | "right"pagesarray of NavigationItemtrigger"hover" | "click"itemsPerColumnnumberNavigationItem[]NavigationItem[]float"center" | "right"pagesarray of NavigationItemtrigger"hover" | "click"NavigationItemButtonNavigationItemtitlestringdescriptionstringpagestringhrefstringiconReact.ReactNodecolorstringdropdownMenuDropdownMenuDropdownMenuitemsarray of NavigationItemRequireditemsPerColumnnumberNavigationItem[]NavigationItem[]float"center" | "right"pagesarray of NavigationItemtrigger"hover" | "click"NavigationItemSocialNavigationItemtitlestringdescriptionstringpagestringhrefstringiconReact.ReactNodecolorstringdropdownMenuDropdownMenuDropdownMenuitemsarray of NavigationItemRequireditemsPerColumnnumberNavigationItem[]NavigationItem[]float"center" | "right"pagesarray of NavigationItemtrigger"hover" | "click"sidebartoparray of NavigationItembottomarray of NavigationItemapiAPIopenapiAPIFileAPIFileMapAPIFileAdvancedAPIFileAdvancedsourcestringRequiredroutestringinfoAPIInfobaseUrlstringauthAPIAuthmethod"bearer" | "basic" | "key"RequirednamestringinputPrefixstringrequestAPIInfoRequestexamplelanguagesstring[]optionsAPIFileOptionsglobalOptionsPerCommandbooleansdk"go" | "python" | "typescript" | "ruby" | "java" | "csharp" | booleanstringstringstring[]string[]graphqlAPIFileAPIFileMapAPIFileAdvancedAPIFileAdvancedsourcestringRequiredroutestringinfoAPIInfobaseUrlstringauthAPIAuthmethod"bearer" | "basic" | "key"RequirednamestringinputPrefixstringrequestAPIInfoRequestexamplelanguagesstring[]optionsAPIFileOptionsglobalOptionsPerCommandbooleansdk"go" | "python" | "typescript" | "ruby" | "java" | "csharp" | booleanstringstringstring[]string[]sourcesAPIFileAPIFileMapAPIFileAdvancedAPIFileAdvancedsourcestringRequiredroutestringinfoAPIInfobaseUrlstringauthAPIAuthmethod"bearer" | "basic" | "key"RequirednamestringinputPrefixstringrequestAPIInfoRequestexamplelanguagesstring[]optionsAPIFileOptionsglobalOptionsPerCommandbooleansdk"go" | "python" | "typescript" | "ruby" | "java" | "csharp" | booleanstringstringstring[]string[]mcpMCPAPIFileMCPAPIFileAdvancedMCPAPIFileAdvancedsourcestringRequiredroutestringinfoMCPAPIInfonamestringtokenstringheadersRecord<string, string>stringstringMCPAPIFileAdvanced[]MCPAPIFileAdvanced[]$$unioncliAPIFileAPIFileMapAPIFileAdvancedAPIFileAdvancedsourcestringRequiredroutestringinfoAPIInfobaseUrlstringauthAPIAuthmethod"bearer" | "basic" | "key"RequirednamestringinputPrefixstringrequestAPIInfoRequestexamplelanguagesstring[]optionsAPIFileOptionsglobalOptionsPerCommandbooleansdk"go" | "python" | "typescript" | "ruby" | "java" | "csharp" | booleanstringstringstring[]string[]integrationsIntegrationsanalyticsIntegrationAnalyticslivesessionIntegrationAnalyticsLiveSessiontrackIdstringRequiredsupportIntegrationSupportchatwootIntegrationSupportChatwootwebsiteTokenstringRequiredbaseURLstringchatwootSettingsJSONintercomIntegrationSupportIntercomappIdstringRequiredapiBasestringlivechatIntegrationSupportLivechatlicenseIdstringRequiredsearchIntegrationSearchalgoliaappIdstringRequiredapiKeystringRequiredoramabooleanabtestingIntegrationABTestingcontextMaxAgenumbercontextStorageKeystringprovidersIntegrationABTestingProvidersgrowthbookIntegrationABTestingGrowthBookapiHoststringRequiredclientKeystringRequiredlaunchdarklyIntegrationABTestingLaunchDarklyenvstringRequireddiagramsDiagramsConfigDiagramsConfigmermaid"img-png" | "img-svg" | "inline-svg" | "pre-mermaid" | booleangraphviz.configinteractivebooleanbooleanbooleanDiagramType[]DiagramType[]editLinkEditLinkbaseUrlstringRequiredtitlestringiconstring.appsAppsDirectorygithubStarIntegrationAppGithubStartitlestringRequiredlabelstringhrefstringRequireddataShowCountbooleandataIconstringdataSizestringariaLabelstringsupademoIntegrationAppSupademoapiKeystringRequiredpluginsarray of PluginsPluginConfig[PluginName, PluginArgs[]]stringstringseoSEOdomainstringmetatagsaiAIllmsTxtLLMsTxtLLMsTxttitlestringRequiredbaseUrlstringRequiredsummarystringsectionsstringstringadvancedAdvancedbasenamestringviteUserConfigcomponentsComponentsbannerWebEditorBannercontentComponentLikeRequiredJSONComponentJSONComponentcomponentstringRequiredpropsRecord<string, any>React.JSX.ElementReact.JSX.Elementstringstringlabelstringkind"secondary"hrefstringiconstringcontextControlsContextControlsfooterWebEditorFooterkind"minimal"logoComponentLikeComponentLikeJSONComponentJSONComponentcomponentstringRequiredpropsRecord<string, any>React.JSX.ElementReact.JSX.ElementstringstringbooleanbooleansocialxstringfacebookstringyoutubestringdiscordstringslackstringgithubstringlinkedinstringinstagramstringhackernewsstringmediumstringtelegramstringblueskystringredditstringlinksWebEditorFooterLinksfootnoteComponentLikeJSONComponentJSONComponentcomponentstringRequiredpropsRecord<string, any>React.JSX.ElementReact.JSX.ElementstringstringfilterSidebarFilterSidebarFilterSidebarplaceholderstringroutesstring[]booleanbooleanengineEnginepathsuniformEngineUniformstorebooleanaccessControlAccessControlproviderRequiredAccessControlProviderOAuthAccessControlProviderOAuthtype"oauth"RequiredauthorizationUrlstringRequiredtokenUrlstringRequiredclientIdstringRequiredscopesstring[]callbackPathstringuserInfoUrlstringgroupsClaimstringAccessControlProviderJWTAccessControlProviderJWTtype"jwt"RequiredloginUrlstringRequiredcallbackPathstringalgorithm"EdDSA" | "RS256" | "HS256"jwksUrlstringsecretstringgroupsClaimstringAccessControlProviderCustomAccessControlProviderCustomtype"custom"RequiredhandlerstringRequireddefaultAccess"public" | "protected"rulesarray of AccessControlRulematchstringRequiredaccess"public" | "protected"Requiredgroupsstring[]loginAccessControlLoginConfigAccessControlLoginConfigpagestringlogostringtitlestringdescriptionstringbackgroundImagestringstringstringunauthorizedBehavior"redirect" | "404"deployAccessControlDeployConfigplatform"netlify-edge" | "vercel-edge" | "cloudflare-edge" | "node-edge"RequiredsessionAccessControlSessionConfigmaxAgenumbercookieNamestringi18nI18nConfigdefaultLocalestringdetectLanguagebooleancatalogsRecord<string, string | TranslationCatalog>
Theme configuration for the application
A theme name.
Path to logo image or object with path to "light" and "dark" mode logo images, and where the logo links to.
Logo configuration interface
Path to the logo in light mode. For example:
`/path/to/logo.svg`
Path to the logo in dark mode. For example:
`/path/to/logo.svg`
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"`
.
External href to when clicking on the logo
The page to link to when clicking on the logo
Font configuration for the theme.
The font family to use.
The font weight to use.
The font src to use.
The font format to use.
Path to the favicon image. For example: /path/to/favicon.svg
The iconify library setup.
The iconify library
The iconify library name
The iconify library version
The default iconify icon name
Merge icons from the library into the default iconify library
Appearance configuration for the theme.
The default color scheme to use.
If
`false`
then the color scheme button will not be displayed.
Colors configuration for the theme.
The primary color of the theme.
The light color of the theme.
The dark color of the theme.
CSS tokens for the theme.
Presets for the theme.
Logo appearance for the theme.
If
`true`
then the logo will be displayed on the sidebar.
If
`true`
then the logo will be displayed on the header.
Search appearance for the theme.
If
`true`
then the search bar will be displayed as a full width.
If
`true`
then the search bar will be displayed on the sidebar.
If
`true`
then the search bar will be displayed in the middle of the header.
If
`true`
then the search bar will be displayed on the right side of the header.
Header appearance for the theme.
If
`true`
then the header external links will display an external arrow.
If
`right`
then separator will be displayed on the right side of the header.
The type of the header.
The button size of the header.
Tabs appearance for the theme.
The tabs to display in the header.
Sidebar appearance for the theme.
If
`true`
then the sidebar will display a scroll shadow.
If
`true`
then the sidebar will display a scroll shadow.
The color of the sidebar scrollbar.
The color of the sidebar scrollbar.
The transition behaviour of the sidebar scroll when navigating to a new page.
Letter-casing of sidebar group headers. Defaults to
`"uppercase"`
; set
`"none"`
to render group labels exactly as authored.
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 appearance for the theme.
Table appearance for the theme.
The kind of the table.
Banner appearance for the theme.
If
`true`
then the banner will have fixed position (always visible).
Content appearance for the theme.
Content decorator for the theme.
Controls the breadcrumbs.
`true`
/
`false`
toggles them; an object
(
AppearanceBreadcrumbs
) additionally configures
`links`
and
`rootLevel`
(both default
`true`
).
Fine-grained breadcrumbs options (the object form of
AppearanceContent.breadcrumbs
).
If
`true`
(default) breadcrumb items that resolve to a real route render as
clickable links; if
`false`
every crumb is plain text.
If
`true`
(default) the top-level segment (the tab/route the page belongs to,
e.g. "Guides") is included; if
`false`
it is omitted.
If
`true`
then the section separator will be displayed.
Footer appearance for the theme.
The footer surface.
Navigation dropdown appearance (header anchors & tabs
`dropdownMenu`
).
Trigger chevron behavior when the menu is open.
`"rotate"`
(default) flips the
chevron;
`"static"`
leaves it unchanged.
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 configuration for the theme.
The maximum number of table of conten§ts levels.
Copy page button
Coder configuration for the theme, including options like syntax highlighting.
If
`true`
then code blocks will have line numbers by default.
If
`true`
then code blocks will have a scrollbar by default.
Syntax highlighting configuration.
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 }]
Custom scripts to be added to the head of the every page.
Paths are relative to the root of the project or absolute.
Navigation configuration
Sidebar navigation type
Sidebar route configuration
Route for this sidebar
The group of the route
The id of the route
Sidebar pages within this route or sub routes
Sidebar configuration
The name of the group
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.)
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.
Page URL type
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" }
```
The URL the page serves at.
The markdown file path, extension-less — like a string page entry
(
`docs/logs.angular`
→
`docs/logs.angular.md`
/
`.mdx`
).
Optional sidebar label override.
Page context controls for THIS page (replaces the global set).
Sidebar configuration
The name of the group
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.)
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.
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.
The icon of the group.
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.
The order of the group.
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).
Behavior options for an
`asToc`
sidebar group (the object form).
Every option defaults to
`true`
—
`asToc: true`
≡
`asToc: {}`
.
TOC-style visual indicator on the group's sidebar items (the vertical
track line the right-hand TOC uses). Default
`true`
.
Breadcrumbs on the composed host page that follow the section being
read (group name / section title, updated by scroll). Default
`true`
.
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).
Pin this item in the sidebar's fixed region (stays visible on scroll).
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.
Object form of
`ComponentPage.component`
: an import path plus optional props.
Path to a default-export React component, relative to the docs project.
Props passed to the component.
The icon of the group.
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.
The order of the group.
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).
Behavior options for an
`asToc`
sidebar group (the object form).
Every option defaults to
`true`
—
`asToc: true`
≡
`asToc: {}`
.
TOC-style visual indicator on the group's sidebar items (the vertical
track line the right-hand TOC uses). Default
`true`
.
Breadcrumbs on the composed host page that follow the section being
read (group name / section title, updated by scroll). Default
`true`
.
Tabs configuration
The navigation item title
The navigation item description
The navigation page, if set it redirects to the page + matches based on routing
The navigation href, if set it redirects but does not match based on routing
The navigation item icon
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`
.
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: [...] }`
).
Object form of
NavigationItem.dropdownMenu
: the menu items plus
menu-level options.
The menu items.
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.
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.
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.
How the
`dropdownMenu`
opens. Defaults to
`"hover"`
.
Sidebar dropdown navigation - navigation through dropdown in the sidebar.
The navigation item title
The navigation item description
The navigation page, if set it redirects to the page + matches based on routing
The navigation href, if set it redirects but does not match based on routing
The navigation item icon
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`
.
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: [...] }`
).
Object form of
NavigationItem.dropdownMenu
: the menu items plus
menu-level options.
The menu items.
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.
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.
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.
How the
`dropdownMenu`
opens. Defaults to
`"hover"`
.
Segment configuration
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 of this segment
Appearance of this segment — a
SegmentAppearance
string, or the
object form
SegmentAppearanceConfig
carrying kind-specific options
(e.g.
`{ kind: "sidebarDropdown", options: { fixed: true } }`
).
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).
`appearance: { kind: "sidebarDropdown", options }`
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).
How a
`logoTrailing`
segment's dropdown opens. Defaults to
`"hover"`
.
`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`
.
`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`
.
Object form of
`ComponentPage.component`
: an import path plus optional props.
Path to a default-export React component, relative to the docs project.
Props passed to the component.
Core interface for navigation items
The navigation item title
The navigation item description
The navigation page, if set it redirects to the page + matches based on routing
The navigation href, if set it redirects but does not match based on routing
The navigation item icon
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`
.
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: [...] }`
).
Object form of
NavigationItem.dropdownMenu
: the menu items plus
menu-level options.
The menu items.
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.
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.
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.
How the
`dropdownMenu`
opens. Defaults to
`"hover"`
.
Anchors navigation - fixed navigation, for anchor-like elements.
Header anchors
Core interface for navigation items
The navigation item title
The navigation item description
The navigation page, if set it redirects to the page + matches based on routing
The navigation href, if set it redirects but does not match based on routing
The navigation item icon
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`
.
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: [...] }`
).
Object form of
NavigationItem.dropdownMenu
: the menu items plus
menu-level options.
Core interface for navigation items
The navigation item title
The navigation item description
The navigation page, if set it redirects to the page + matches based on routing
The navigation href, if set it redirects but does not match based on routing
The navigation item icon
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`
.
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: [...] }`
).
Object form of
NavigationItem.dropdownMenu
: the menu items plus
menu-level options.
The menu items.
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.
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.
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.
How the
`dropdownMenu`
opens. Defaults to
`"hover"`
.
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.
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.
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.
How the
`dropdownMenu`
opens. Defaults to
`"hover"`
.
Core interface for navigation items
The navigation item title
The navigation item description
The navigation page, if set it redirects to the page + matches based on routing
The navigation href, if set it redirects but does not match based on routing
The navigation item icon
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`
.
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: [...] }`
).
Object form of
NavigationItem.dropdownMenu
: the menu items plus
menu-level options.
The menu items.
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.
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.
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.
How the
`dropdownMenu`
opens. Defaults to
`"hover"`
.
Core interface for navigation items
The navigation item title
The navigation item description
The navigation page, if set it redirects to the page + matches based on routing
The navigation href, if set it redirects but does not match based on routing
The navigation item icon
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`
.
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: [...] }`
).
Object form of
NavigationItem.dropdownMenu
: the menu items plus
menu-level options.
The menu items.
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.
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.
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.
How the
`dropdownMenu`
opens. Defaults to
`"hover"`
.
Sidebar anchors
Per-locale navigation block. Same shape as
`Navigation`
plus locale fields.
ISO 639-1 code for this locale. Used in URLs (
`/{language}/...`
).
Native display name shown in the locale switcher (
`Polski`
, not
`Polish`
).
Marks this entry as the default locale (URLs unprefixed).
Ignored when
`i18n.defaultLocale`
is set explicitly.
If neither is set, the first entry wins.
Text direction. Sets
`<html dir>`
on pages of this locale.
Defaults to
`"ltr"`
.
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 navigation type
Sidebar route configuration
Route for this sidebar
The group of the route
The id of the route
Sidebar pages within this route or sub routes
Sidebar configuration
The name of the group
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.)
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.
Page URL type
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" }
```
The URL the page serves at.
The markdown file path, extension-less — like a string page entry
(
`docs/logs.angular`
→
`docs/logs.angular.md`
/
`.mdx`
).
Optional sidebar label override.
Page context controls for THIS page (replaces the global set).
Sidebar configuration
The name of the group
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.)
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.
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.
The icon of the group.
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.
The order of the group.
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).
Behavior options for an
`asToc`
sidebar group (the object form).
Every option defaults to
`true`
—
`asToc: true`
≡
`asToc: {}`
.
TOC-style visual indicator on the group's sidebar items (the vertical
track line the right-hand TOC uses). Default
`true`
.
Breadcrumbs on the composed host page that follow the section being
read (group name / section title, updated by scroll). Default
`true`
.
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).
Pin this item in the sidebar's fixed region (stays visible on scroll).
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.
Object form of
`ComponentPage.component`
: an import path plus optional props.
Path to a default-export React component, relative to the docs project.
Props passed to the component.
The icon of the group.
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.
The order of the group.
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).
Behavior options for an
`asToc`
sidebar group (the object form).
Every option defaults to
`true`
—
`asToc: true`
≡
`asToc: {}`
.
TOC-style visual indicator on the group's sidebar items (the vertical
track line the right-hand TOC uses). Default
`true`
.
Breadcrumbs on the composed host page that follow the section being
read (group name / section title, updated by scroll). Default
`true`
.
Tabs configuration
The navigation item title
The navigation item description
The navigation page, if set it redirects to the page + matches based on routing
The navigation href, if set it redirects but does not match based on routing
The navigation item icon
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`
.
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: [...] }`
).
Object form of
NavigationItem.dropdownMenu
: the menu items plus
menu-level options.
The menu items.
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.
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.
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.
How the
`dropdownMenu`
opens. Defaults to
`"hover"`
.
Sidebar dropdown for this locale.
The navigation item title
The navigation item description
The navigation page, if set it redirects to the page + matches based on routing
The navigation href, if set it redirects but does not match based on routing
The navigation item icon
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`
.
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: [...] }`
).
Object form of
NavigationItem.dropdownMenu
: the menu items plus
menu-level options.
The menu items.
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.
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.
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.
How the
`dropdownMenu`
opens. Defaults to
`"hover"`
.
Segment configuration
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 of this segment
Appearance of this segment — a
SegmentAppearance
string, or the
object form
SegmentAppearanceConfig
carrying kind-specific options
(e.g.
`{ kind: "sidebarDropdown", options: { fixed: true } }`
).
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).
`appearance: { kind: "sidebarDropdown", options }`
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).
How a
`logoTrailing`
segment's dropdown opens. Defaults to
`"hover"`
.
`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`
.
`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`
.
Object form of
`ComponentPage.component`
: an import path plus optional props.
Path to a default-export React component, relative to the docs project.
Props passed to the component.
Core interface for navigation items
The navigation item title
The navigation item description
The navigation page, if set it redirects to the page + matches based on routing
The navigation href, if set it redirects but does not match based on routing
The navigation item icon
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`
.
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: [...] }`
).
Object form of
NavigationItem.dropdownMenu
: the menu items plus
menu-level options.
The menu items.
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.
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.
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.
How the
`dropdownMenu`
opens. Defaults to
`"hover"`
.
Anchors for this locale.
Header anchors
Core interface for navigation items
The navigation item title
The navigation item description
The navigation page, if set it redirects to the page + matches based on routing
The navigation href, if set it redirects but does not match based on routing
The navigation item icon
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`
.
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: [...] }`
).
Object form of
NavigationItem.dropdownMenu
: the menu items plus
menu-level options.
Core interface for navigation items
The navigation item title
The navigation item description
The navigation page, if set it redirects to the page + matches based on routing
The navigation href, if set it redirects but does not match based on routing
The navigation item icon
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`
.
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: [...] }`
).
Object form of
NavigationItem.dropdownMenu
: the menu items plus
menu-level options.
The menu items.
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.
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.
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.
How the
`dropdownMenu`
opens. Defaults to
`"hover"`
.
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.
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.
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.
How the
`dropdownMenu`
opens. Defaults to
`"hover"`
.
Core interface for navigation items
The navigation item title
The navigation item description
The navigation page, if set it redirects to the page + matches based on routing
The navigation href, if set it redirects but does not match based on routing
The navigation item icon
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`
.
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: [...] }`
).
Object form of
NavigationItem.dropdownMenu
: the menu items plus
menu-level options.
The menu items.
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.
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.
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.
How the
`dropdownMenu`
opens. Defaults to
`"hover"`
.
Core interface for navigation items
The navigation item title
The navigation item description
The navigation page, if set it redirects to the page + matches based on routing
The navigation href, if set it redirects but does not match based on routing
The navigation item icon
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`
.
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: [...] }`
).
Object form of
NavigationItem.dropdownMenu
: the menu items plus
menu-level options.
The menu items.
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.
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.
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.
How the
`dropdownMenu`
opens. Defaults to
`"hover"`
.
Sidebar anchors
API Docs configuration
API file configuration. Can be a path, an array of paths, a map of paths, or an advanced configuration
API file map type
API file advanced type
Source configuration
Route configuration
API information configuration
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.
Authentication information
The authentication strategy used for all API endpoints
The name of the authentication parameter used in the API playground.
If method is basic, the format should be [usernameName]:[passwordName]
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 configuration
Configurations for the auto-generated API request examples
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
Preset-specific rendering options (e.g. CLI).
(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-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.
API file configuration. Can be a path, an array of paths, a map of paths, or an advanced configuration
API file map type
API file advanced type
Source configuration
Route configuration
API information configuration
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.
Authentication information
The authentication strategy used for all API endpoints
The name of the authentication parameter used in the API playground.
If method is basic, the format should be [usernameName]:[passwordName]
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 configuration
Configurations for the auto-generated API request examples
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
Preset-specific rendering options (e.g. CLI).
(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-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.
API file configuration. Can be a path, an array of paths, a map of paths, or an advanced configuration
API file map type
API file advanced type
Source configuration
Route configuration
API information configuration
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.
Authentication information
The authentication strategy used for all API endpoints
The name of the authentication parameter used in the API playground.
If method is basic, the format should be [usernameName]:[passwordName]
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 configuration
Configurations for the auto-generated API request examples
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
Preset-specific rendering options (e.g. CLI).
(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-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.
MCP API file configuration. URL shorthand, advanced, or named map.
MCP server URL (http/https/sse).
Sidebar route prefix to nest the generated pages under.
Per-source options.
Display name for the server in the docs.
Bearer token sent as
`Authorization: Bearer <token>`
.
Supports
`$ENV_VAR`
substitution via the standard settings env replacement.
Additional request headers (e.g. cookies, custom API keys).
API file configuration. Can be a path, an array of paths, a map of paths, or an advanced configuration
API file map type
API file advanced type
Source configuration
Route configuration
API information configuration
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.
Authentication information
The authentication strategy used for all API endpoints
The name of the authentication parameter used in the API playground.
If method is basic, the format should be [usernameName]:[passwordName]
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 configuration
Configurations for the auto-generated API request examples
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
Preset-specific rendering options (e.g. CLI).
(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-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.
Integrations configuration
Configurations to add third-party analytics integrations.
See full list of supported analytics here.
LiveSession analytics configuration
LiveSession's TrackID
Configurations to add third-party support integrations.
Chatwoot support configuration
Chatwoot website token
Chatwoot base URL
Chatwoot settings
Intercom support configuration
Intercom app ID
Intercom API base
Livechat support configuration
Livechat license ID
Configurations to add third-party search integrations.
See full list of supported search here.
Algolia search configuration
Algolia application ID
Algolia API key
A/B testing configuration
Context max age in milliseconds
Context storage key used to store the context in the browser storage
Providers configuration
GrowthBook configuration
GrowthBook API host
GrowthBook client key
LaunchDarkly configuration
LaunchDarkly environment key
Diagrams configuration
Diagrams configuration object
Mermaid diagram configuration
-
`true`
: Enable with default settings
-
`{ strategy: 'img-svg' }`
: Enable with custom settings
Graphviz diagram configuration
-
`true`
: Enable with default settings
-
`{ engine: 'neato' }`
: Enable with custom settings
Detailed diagram config, useful for e.g setting diagram's interactive.
Edit link configuration
The base URL for the edit link
The title for the edit link
The icon for the edit link
Custom apps directory.
Github star app configuration.
The title of the Github button
The label of the Github Button
The href of the Github project
The data-show-count of the Github project
The data-icon of the Github button
The data-size of the Github button
The aria-label of the Github button
Supademo app configuration.
The Supademo API key
Plugin configuration
SEO configuration
Domain name
Meta tags
AI configuration
LLMs txt configuration
LLMs txt configuration
Title of the LLMs txt
Base URL of the LLMs txt
Description of the LLMs txt
Sections of the LLMs txt
Advanced configuration
basename
Custom Vite configuration overrides.
Merged with xyd's internal Vite config.
Components configuration
WebEditor banner configuration
A type that can be used to represent a component-like structure.
JSON representation of a component.
The component type, e.g. "Button", "Card", etc.
The component's children, which can be a string, an array of strings, or an array of JSONComponent objects.
Banner label.
Banner kind.
Banner href.
Banner icon.
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 (
`{ page, contextControls }`
).
WebEditor footer configuration
A type that can be used to represent a component-like structure.
JSON representation of a component.
The component type, e.g. "Button", "Card", etc.
The component's children, which can be a string, an array of strings, or an array of JSONComponent objects.
Footer socials
Footer links
A type that can be used to represent a component-like structure.
JSON representation of a component.
The component type, e.g. "Button", "Card", etc.
The component's children, which can be a string, an array of strings, or an array of JSONComponent objects.
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.
Configuration for the built-in sidebar filter input (
`components.filterSidebar`
).
Placeholder text for the filter input. Defaults to
`"Filter sidebar"`
.
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.
Engine configuration - advanced engine-like configuration
Path aliases for imports. Avoid long relative paths by creating shortcuts.
Uniform configuration
If
`true`
then virtual pages will not created and generated content will be stored on disk
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.
Authentication provider configuration
OAuth 2.0 authorization URL
OAuth 2.0 token endpoint URL
OAuth 2.0 client ID. Use $ENV_VAR syntax for secrets.
OAuth 2.0 scopes to request
Callback path for OAuth redirect.
URL to fetch user info after auth (provides groups)
Field in user info response containing groups/roles
URL to redirect unauthenticated users for login
Callback path where JWT is delivered via hash fragment.
JWT signing algorithm.
JWKS URL for key verification (EdDSA/RS256)
Shared secret for HS256 verification. Use $ENV_VAR syntax.
JWT claim name containing user groups/roles
Path to custom auth handler module
Default access level for all pages.
"protected" = all pages require auth unless marked public.
"public" = all pages are public unless marked protected.
Pattern-based access rules, evaluated in order. First match wins.
Glob pattern matching page paths
Access level for matched pages
Groups allowed access (only for "protected" access)
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.
Custom login page (path to mdx file)
Logo to display on the default login page
Title text on the login page
Description text on the login page
Background image URL for the login page
Behavior when user is unauthorized.
"redirect" sends to login page.
"404" shows not-found page (hides existence of protected page).
Deployment platform for server-side content protection
Target deployment platform
Session/token configuration
Session duration in seconds.
Cookie/storage key name.
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.
Explicit default locale. Overrides any
`default: true`
shorthand on
`navigation.languages[]`
entries when set.
Must match a
`language`
declared in
`navigation.languages[]`
.
When
`true`
, redirect
`/`
based on
`navigator.language`
/
`xyd-locale`
cookie. Default
`false`
.
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/{language}.json`
files at the project root.
Environment Variables
Load environment variables from .env files to keep sensitive values out of your code.
Supported files: .env, .env.local, .env.development, .env.production
Usage:
JSON Schema Validation
The docs.json file is validated against a JSON schema to ensure proper configuration. You can reference the schema by including:
Custom Vite ConfigurationBeta
You can customize the Vite configuration via advanced.vite. This is useful for remote development environments, custom aliases, and other Vite-level settings.
The config is merged with xyd's internal Vite config using Vite's mergeConfig:
Common use cases:
server.allowedHosts— allow access from remote dev environments (e.g., code-server, Gitpod)server.port— override the default dev server portresolve.alias— add custom import aliasesdefine— inject compile-time constants
The vite option applies to both the dev server and production builds. See the Vite configuration reference for all available options.
Code-Based SettingsComing Soon
If you feel that the JSON configuration is not enough, you can use the TypeScript/React based configuration to have more control and use APIs that are not available in the JSON configuration.
For example, you could define a custom components, adds custom markdown plugins or other customization stuff:
Built with
Show your support! Star us on GitHub ⭐️