xyd 0.1.0-beta - Coming Soon

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:

    theme
    Theme
    Theme configuration for the application
      name
      "poetry" | "cosmo" | "opener" | "picasso" | "gusto" | "solar" | 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`
          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
        { [token: string]: string; }
        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.
        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
          boolean
          If `true` then the breadcrumbs will be displayed.
          sectionSeparator
          boolean
          If `true` then the section separator will be displayed.
        footer
        AppearanceFooter
        Footer appearance for the theme.
          surface
          "page"
          The footer surface.
      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] @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
      Required
      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
          pages
          array of PageURL
          Page URL type
            Sidebar
            Sidebar
            Sidebar configuration
              group
              string
              The name of the group
              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.
              order
              Order
              The order of the group.
            string
            string
          icon
          string
          The icon of the group.
          order
          Order
          The order of the group.
        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
      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
      segments
      array of Segment
      Segment configuration
        route
        string
        Required
        Route for this segment
        title
        string
        Title of this segment
        appearance
        "sidebarDropdown"
        Appearance of this segment. If 'sidebarDropdown' then show this segment as a dropdown in the sidebar if match.
        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
      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
          NavigationItemButton
          NavigationItemButton
            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
            NavigationItem & { button: "primary"
            NavigationItem & { button: "primary"
            "secondary"; }
            "secondary"; }
          NavigationItemSocial
          NavigationItemSocial
            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
            NavigationItem & { social: Social; }
            NavigationItem & { social: Social; }
        sidebar
        { top?: NavigationItem[]; bottom?: NavigationItem[]; }
        Sidebar anchors
          top
          array of NavigationItem
          bottom
          array of NavigationItem
    api
    API
    API Docs configuration
      openapi
      APIFile
      API file configuration. Can be a path, an array of paths, a map of paths, or an advanced configuration
        APIFileMap
        APIFileMap { [name: string]: string | APIFileAdvanced; }
        API file map type
        APIFileAdvanced
        APIFileAdvanced
        API file advanced type
          source
          string
          Required
          Source configuration
          route
          string
          Route configuration
          info
          APIInfo
          API information configuration
            baseUrl
            string
            The base url for all API endpoints. If baseUrl is an array, it will enable for multiple base url options that the user can toggle.
            auth
            APIAuth
            Authentication information
              method
              "bearer" | "basic" | "key"
              Required
              The authentication strategy used for all API endpoints
            name
            string
            The name of the authentication parameter used in the API playground. If method is basic, the format should be [usernameName]:[passwordName]
            inputPrefix
            string
            The default value that's designed to be a prefisx for the authentication input field. E.g. If an inputPrefix of AuthKey would inherit the default input result of the authentication field as AuthKey.
            request
            APIInfoRequest
            Request configuration
              example
              { languages?: string[]; }
              Configurations for the auto-generated API request examples
                languages
                string[]
                An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing x-codeSamples or use our default languages which include bash, python, javascript, php, go, java
        string
        string
        string[]
        string[]
      graphql
      APIFile
      API file configuration. Can be a path, an array of paths, a map of paths, or an advanced configuration
        APIFileMap
        APIFileMap { [name: string]: string | APIFileAdvanced; }
        API file map type
        APIFileAdvanced
        APIFileAdvanced
        API file advanced type
          source
          string
          Required
          Source configuration
          route
          string
          Route configuration
          info
          APIInfo
          API information configuration
            baseUrl
            string
            The base url for all API endpoints. If baseUrl is an array, it will enable for multiple base url options that the user can toggle.
            auth
            APIAuth
            Authentication information
              method
              "bearer" | "basic" | "key"
              Required
              The authentication strategy used for all API endpoints
            name
            string
            The name of the authentication parameter used in the API playground. If method is basic, the format should be [usernameName]:[passwordName]
            inputPrefix
            string
            The default value that's designed to be a prefisx for the authentication input field. E.g. If an inputPrefix of AuthKey would inherit the default input result of the authentication field as AuthKey.
            request
            APIInfoRequest
            Request configuration
              example
              { languages?: string[]; }
              Configurations for the auto-generated API request examples
                languages
                string[]
                An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing x-codeSamples or use our default languages which include bash, python, javascript, php, go, java
        string
        string
        string[]
        string[]
      sources
      APIFile
      API file configuration. Can be a path, an array of paths, a map of paths, or an advanced configuration
        APIFileMap
        APIFileMap { [name: string]: string | APIFileAdvanced; }
        API file map type
        APIFileAdvanced
        APIFileAdvanced
        API file advanced type
          source
          string
          Required
          Source configuration
          route
          string
          Route configuration
          info
          APIInfo
          API information configuration
            baseUrl
            string
            The base url for all API endpoints. If baseUrl is an array, it will enable for multiple base url options that the user can toggle.
            auth
            APIAuth
            Authentication information
              method
              "bearer" | "basic" | "key"
              Required
              The authentication strategy used for all API endpoints
            name
            string
            The name of the authentication parameter used in the API playground. If method is basic, the format should be [usernameName]:[passwordName]
            inputPrefix
            string
            The default value that's designed to be a prefisx for the authentication input field. E.g. If an inputPrefix of AuthKey would inherit the default input result of the authentication field as AuthKey.
            request
            APIInfoRequest
            Request configuration
              example
              { languages?: string[]; }
              Configurations for the auto-generated API request examples
                languages
                string[]
                An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing x-codeSamples or use our default languages which include bash, python, javascript, php, go, java
        string
        string
        string[]
        string[]
    integrations
    Integrations
    Integrations configuration
      analytics
      IntegrationAnalytics
      Configurations to add third-party analytics integrations. See full list of supported analytics here.
        livesession
        IntegrationAnalyticsLiveSession
        LiveSession analytics configuration
          trackId
          string
          Required
          LiveSession's TrackID
      support
      IntegrationSupport
      Configurations to add third-party support integrations.
        chatwoot
        IntegrationSupportChatwoot
        Chatwoot support configuration
          websiteToken
          string
          Required
          Chatwoot website token
          baseURL
          string
          Chatwoot base URL
          chatwootSettings
          JSON
          Chatwoot settings
        intercom
        IntegrationSupportIntercom
        Intercom support configuration
          appId
          string
          Required
          Intercom app ID
          apiBase
          string
          Intercom API base
        livechat
        IntegrationSupportLivechat
        Livechat support configuration
          licenseId
          string
          Required
          Livechat license ID
      search
      IntegrationSearch
      Configurations to add third-party search integrations. See full list of supported search here.
        algolia
        { appId: string; apiKey: string; }
        Algolia search configuration
          appId
          string
          Required
          Algolia application ID
          apiKey
          string
          Required
          Algolia API key
        orama
        boolean
      abtesting
      IntegrationABTesting
      A/B testing configuration
        contextMaxAge
        number
        Context max age in milliseconds
        contextStorageKey
        string
        Context storage key used to store the context in the browser storage
        providers
        IntegrationABTestingProviders
        Providers configuration
          growthbook
          IntegrationABTestingGrowthBook
          GrowthBook configuration
            apiHost
            string
            Required
            GrowthBook API host
            clientKey
            string
            Required
            GrowthBook client key
          launchdarkly
          IntegrationABTestingLaunchDarkly
          LaunchDarkly configuration
            env
            string
            Required
            LaunchDarkly environment key
      diagrams
      boolean
      Diagrams configuration
      editLink
      EditLink
      Edit link configuration
        baseUrl
        string
        Required
        The base URL for the edit link
        title
        string
        The title for the edit link
        icon
        string
        The icon for the edit link
      .apps
      AppsDirectory
      Custom apps directory.
        githubStar
        IntegrationAppGithubStar
        Github star app configuration.
          title
          string
          Required
          The title of the Github button
          label
          string
          The label of the Github Button
          href
          string
          Required
          The href of the Github project
          dataShowCount
          boolean
          The data-show-count of the Github project
          dataIcon
          string
          The data-icon of the Github button
          dataSize
          string
          The data-size of the Github button
          ariaLabel
          string
          The aria-label of the Github button
        supademo
        IntegrationAppSupademo
        Supademo app configuration.
          apiKey
          string
          Required
          The Supademo API key
    plugins
    array of Plugins
    Plugin configuration
      PluginConfig
      [PluginName, PluginArgs[]]
      string
      string
    seo
    SEO
    SEO configuration
      domain
      string
      Domain name
      metatags
      { [tag: string]: string; }
      Meta tags
    ai
    AI
    AI configuration
      llmsTxt
      LLMs txt configuration
        LLMsTxt
        LLMsTxt
        LLMs txt configuration
          title
          string
          Required
          Title of the LLMs txt
          baseUrl
          string
          Required
          Base URL of the LLMs txt
          summary
          string
          Description of the LLMs txt
          sections
          { [section: string]: { title: string; url: string; description: string; }; }
          Sections of the LLMs txt
        string
        string
    advanced
    Advanced
    Advanced configuration
      basename
      string
      basename
    components
    Components
    Components configuration
      banner
      WebEditorBanner
      WebEditor banner configuration
        content
        ComponentLike
        Required
        A type that can be used to represent a component-like structure.
          JSONComponent
          JSONComponent
          JSON representation of a component.
            component
            string
            Required
            The component type, e.g. "Button", "Card", etc.
            props
            Record<string, any>
            The component's children, which can be a string, an array of strings, or an array of JSONComponent objects.
          React.JSX.Element
          React.JSX.Element
          string
          string
        label
        string
        Banner label.
        kind
        "secondary"
        Banner kind.
        href
        string
        Banner href.
        icon
        string
        Banner icon.
      footer
      WebEditorFooter
      WebEditor footer configuration
        kind
        "minimal"
        logo
          ComponentLike
          ComponentLike
          A type that can be used to represent a component-like structure.
            JSONComponent
            JSONComponent
            JSON representation of a component.
              component
              string
              Required
              The component type, e.g. "Button", "Card", etc.
              props
              Record<string, any>
              The component's children, which can be a string, an array of strings, or an array of JSONComponent objects.
            React.JSX.Element
            React.JSX.Element
            string
            string
          boolean
          boolean
        social
        { [K in Social]?: string; }
        Footer socials
          x
          string
          facebook
          string
          youtube
          string
          discord
          string
          slack
          string
          github
          string
          linkedin
          string
          instagram
          string
          hackernews
          string
          medium
          string
          telegram
          string
          bluesky
          string
          reddit
          string
        links
        WebEditorFooterLinks
        Footer links
        footnote
        ComponentLike
        A type that can be used to represent a component-like structure.
          JSONComponent
          JSONComponent
          JSON representation of a component.
            component
            string
            Required
            The component type, e.g. "Button", "Card", etc.
            props
            Record<string, any>
            The component's children, which can be a string, an array of strings, or an array of JSONComponent objects.
          React.JSX.Element
          React.JSX.Element
          string
          string
    engine
    Engine
    Engine configuration - advanced engine-like configuration
      paths
      { [key: string]: string[]; }
      Path aliases for imports. Avoid long relative paths by creating shortcuts.
      uniform
      EngineUniform
      Uniform configuration
        store
        boolean
        If `true` then virtual pages will not created and generated content will be stored on disk

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:

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 ⭐️