logo
On this page

Customize with json file

INFO

Refer to the Getting Started Configuration for examples.

Overview

docuo.config.json contains configurations for your site and is placed in the root directory of your site. This file is run in Node.js and should returns a standard json format of content.

Here's an example:

docuo.config.json
{
  "title": "Your site title",
  "favicon": "Your site favicon"
}
1
Copied!
TIP

Refer to Syntax to declare docuo.config.json for a more exhaustive list of examples and explanations.

Required fields

title

  • Type: string

Title for your website. It will be used in metadata and as browser tab title.

docuo.config.json
{
  "title": "Your site title"
}
1
Copied!

themeConfig

  • Type: Object

The theme configuration object to customize your site UI like navbar and footer.

Example:

docuo.config.json
{
  "themeConfig": {
    "navbar": {
      "title": "Your navbar title",
      "logo": "Your navbar logo",
      "items": [
        {
          "type": "docSidebar",
          "sidebarIds": ["mySidebar"],
          "label": "Documentation"
        }
      ]
    },
    "footer": {
      "logo": "Your footer logo",
      "caption": "Your caption",
      "links": [
        {
          "title": "Product",
          "items": [
            {
              "label": "documentation",
              "to": "/"
            }
          ]
        }
      ],
      "socials": [
        {
          "logo": "Twitter",
          "href": "Your twitter url"
        },
        {
          "logo": "LinkedIn",
          "href": "Your linkedin url"
        },
        {
          "logo": "Discord",
          "href": "Your discord url"
        },
        {
          "logo": "GitHub",
          "href": "Your github url"
        }
      ]
    },
    "colorMode": {
      "defaultMode": "light",
      "disableSwitch": false,
      "respectPrefersColorScheme": false
    }
  }
}
1
Copied!

Optional fields

favicon

  • Type: string | undefined

Path to your site favicon. It must be a URL that can be used in link's href. For example, if your favicon is in static/image/favicon.ico:

TIP

The default static direcory is a static directory. The files under the paths will be copied to the build output as-is,which are absolute paths.

docuo.config.json
{
  "favicon": "image/favicon.ico"
}
1
Copied!

Theme configuration

Accepted fields:

NameTypeDefaultDescription
titlestringundefinedTitle for the navbar.
logoSee belowundefinedCustomization of the logo url.
iconRedirectUrlstringundefinedLink to navigate to when the logo is clicked.
itemsNavbarItem[][]A list of navbar items. See specification below.

The logo can be placed in static folder.

TIP

The default static direcory is a static directory. The files under the paths will be copied to the build output as-is,which are absolute paths.

Example configuration:

docuo.config.json
{
  "themeConfig": {
    "navbar": {
      "title": "Your site title",
      "logo": "image/logo.png"
    }
  }
}
1
Copied!

If your website has configured dark mode and you have another logo for dark mode, you can also configure logo like this:

docuo.config.json
{
  "themeConfig": {
    "navbar": {
      "title": "Your site title",
      "logo": {
        "light": "image/logo_light.png",
        "dark": "image/logo_dark.png"
      }
    }
  }
}
1
Copied!

The default URL of your logo will be redirected to your base URL of your site. You can specify your own logo redirect URL. If the URL is an external link, it will open in a new tab.

Example configuration:

docuo.config.json
{
  "themeConfig": {
    "navbar": {
      "title": "Your site title",
      "logo": "image/logo.png",
      "iconRedirectUrl": "https://docuo.io"
    }
  }
}
1
Copied!

You can add items to the navbar using themeConfig.navbar.items.

docuo.config.json
{
  "themeConfig": {
    "navbar": {
      "items": [
        {
          "type": "docSidebar",
          "label": "Docs",
          "sidebarIds": ["mySidebar"],
          "position": "left"
        },
        {
          "type": "default",
          "label": "Blog",
          "href": "https://spreading.ai/blog",
          "position": "right"
        },
        {
          "type": "dropdown",
          "label": "Dropdown",
          "position": "right",
          "items": [
            {
              "type": "docSidebar",
              "label": "NavItem1",
              "sidebarIds": ["mySidebar"]
            },
            {
              "type": "default",
              "label": "NavItem2",
              "href": "https://spreading.ai/blog"
            }
          ]
        }
      ]
    }
  }
}
1
Copied!

The items can have different behaviors based on the type field. The sections below will introduce you to all the types of navbar items available.

  • Navbar link

By default, Navbar items are regular links (internal or external).

Accepted fields:

NameTypeDefaultDescription
type"default"OptionalSets the type of this item to a link.
labelstringRequiredThe name to be shown for this item.
tostringRequiredClient-side routing, used for navigating within the website.
hrefstringRequiredA full-page navigation, used for navigating outside of the website. Only one of to or href should be used.
position"left" | "right""left"The side of the navbar this item should appear on.

Example configuration:

docuo.config.json
{
  "themeConfig": {
    "navbar": {
      "items": [
        {
          "to": "/introduction",
          "label": "Introduction",
          "position": "left"
        }
      ]
    }
  }
}
1
Copied!
  • Navbar dropdown

Navbar items of the type dropdown has the additional items field, an inner array of navbar items.

Navbar dropdown items only accept the following "link-like" item types:

Note that the dropdown base item is a clickable link as well, so this item can receive any of the props of a plain navbar link.

Accepted fields:

NameTypeDefaultDescription
type"dropdown"OptionalSets the type of this item to a dropdown.
labelstringRequiredThe name to be shown for this item.
itemsLinkLikeItem[]RequiredThe items to be contained in the dropdown.
position"left" | "right""left"The side of the navbar this item should appear on.

Example configuration:

docuo.config.json
{
  "themeConfig": {
    "navbar": {
      "items": [
        {
          "type": "dropdown",
          "label": "Dropdown",
          "position": "left",
          "items": [
            {
              "type": "docSidebar",
              "label": "NavItem1",
              "sidebarIds": ["mySidebar"]
            },
            {
              "type": "default",
              "label": "NavItem2",
              "href": "https://spreading.ai/blog"
            }
          ]
        }
      ]
    }
  }
}
1
Copied!
  • Navbar linked to a sidebar

You can link a navbar item to the first document link (which can be a doc link or a generated category index) of a given sidebar without having to hardcode a doc ID.

Accepted fields:

NameTypeDefaultDescription
type"docSidebar"RequiredSets the type of this navbar item to a sidebar's first document.
sidebarIdsstring[]RequiredThe ID list of the sidebar that this item is linked to.
labelstringFirst document link's sidebar labelThe name to be shown for this item.
position"left" | "right""left"The side of the navbar this item should appear on.
docsInstanceIdstring"default"The ID of the docs plugin that the sidebar belongs to.
TIP

Use this navbar item type if your sidebar is updated often and the order is not stable.

Example configuration:

docuo.config.json
{
  "themeConfig": {
    "navbar": {
      "items": [
        {
          "type": "docSidebar",
          "label": "Docs",
          "sidebarIds": ["mySidebar"],
          "position": "left"
        }
      ]
    }
  }
}
1
Copied!

The sidebarId of the navbar item corresponds to one of the sidebar keys, which is "mySidebar".

sidebars.json
{
  "mySidebar": [
    {
      "type": "autogenerated",
      "dirName": "."
    }
  ]
}
1
Copied!

You can add logo and a copyright to the footer via themeConfig.footer. Logo can be placed in static folder. Logo URL works in the same way of the navbar logo.

TIP

The default static direcory is a static directory. The files under the paths will be copied to the build output as-is,which are absolute paths.

Accepted fields:

NameTypeDefaultDescription
logoLogoundefinedCustomization of the logo url. See Navbar logo for details.
copyrightstringundefinedThe copyright message to be displayed at the bottom.
captionstringundefinedThe caption message to be displayed at the bottom.
linksFooterLink[][]The link groups to be present.
socialsSocialItem[][]The social link groups to be present.

Example configuration:

docuo.config.json
{
  "themeConfig": {
    "footer": {
      "logo": "image/logo.png",
      "copyright": "xxx",
      "caption": "xxx"
    }
  }
}
1
Copied!

If your website has configured dark mode and you have another logo for dark mode, you can also configure your footer logo like this:

docuo.config.json
{
  "themeConfig": {
    "footer": {
      "logo": {
        "light": "image/logo_light.png",
        "dark": "image/logo_dark.png"
      }
    }
  }
}
1
Copied!

You can add links to the footer via themeConfig.footer.links. There are two types of footer configurations: multi-column footers and simple footers.

Multi-column footer links have a title and a list of FooterItems for each column.

NameTypeDefaultDescription
titlestringundefinedLabel of the section of these links.
itemsFooterItem[][]Links in this section.

Accepted fields of each FooterItem:

NameTypeDefaultDescription
labelstringRequiredText to be displayed for this link.
tostringRequiredClient-side routing, used for navigating within the website.
hrefstringRequiredA full-page navigation, used for navigating outside of the website. Only one of to or href should be used.

Example multi-column configuration:

docuo.config.json
{
  "themeConfig": {
    "footer": {
      "links": [
        {
          "title": "Product",
          "items": [
            {
              "label": "documentation",
              "to": "/"
            }
          ]
        }
      ]
    }
  }
}
1
Copied!

A simple footer just has a list of FooterItems displayed in a row.

Example simple configuration:

docuo.config.json
{
  "themeConfig": {
    "footer": {
      "links": [
        {
          "label": "documentation",
          "to": "/"
        }
      ]
    }
  }
}
1
Copied!

You can add socials to the footer via themeConfig.footer.socials.

Accepted fields of each SocialItem:

NameTypeDefaultDescription
logoLogo | DefaultSocialNameRequiredCustomization of the logo url. See Navbar logo for details.
Or the name of the built-in social media icon
hrefstringRequiredA full-page navigation, used for navigating outside of the website.

The default items ofDefaultSocialName include:“LinkedIn”、“Twitter”、“Facebook”、“Facebook”、“GitHub”、“Discord”

docuo.config.json
{
  "themeConfig": {
    "footer": {
      "socials": [
        {
          "logo": "image/twitter.svg",
          "href": "https://twitter.com/docuo_team"
        },
        {
          "logo": "LinkedIn",
          "href": "https://www.linkedin.com/company/spreadingai"
        },
        {
          "logo": "Discord",
          "href": "https://discord.gg/W8p93wcR"
        },
        {
          "logo": "GitHub",
          "href": "https://github.com/spreadingai"
        }
      ]
    }
  }
}
1
Copied!

Color mode

You can customize your color mode within the colorMode object.

Accepted fields:

NameTypeDefaultDescription
defaultMode'light' | 'dark''light'The color mode when user first visits the site.
disableSwitchbooleanfalseHides the switch in the navbar. Useful if you want to support a single color mode.
respectPrefersColorSchemebooleanfalseWhether to use the prefers-color-scheme media-query, using user system preferences, instead of the hardcoded defaultMode.

Example configuration:

docuo.config.json
{
  "themeConfig": {
    "colorMode": {
      "defaultMode": "light",
      "disableSwitch": false,
      "respectPrefersColorScheme": true
    }
  }
}
1
Copied!
Warning
With respectPrefersColorScheme: true, the defaultMode is overridden by user system preferences.

Primary Colors

You can customize your primary colors within the colors object.

Accepted fields:

NameTypeDefaultDescription
primaryLightstring'#1ABD00'Primary color for highlighted content in light mode.
primaryDarkstring'#05EC07'Primary color for highlighted content in dark mode.

Example configuration:

docuo.config.json
{
  "themeConfig": {
    "colors": {
      "primaryLight": "#1ABD00",
      "primaryDark": "#05EC07"
    }
  }
}
1
Copied!