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

{
  "title": "Your site title",
  "favicon": "Your site favicon"
}

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. Will be used in metadata and as browser tab title.

docuo.config

{
  "title": "Your site title"
}

Copied!

`themeConfig`

Type: Object

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

Example:

docuo.config

{
  "themeConfig": {
    "navbar": {
      "title": "Your navbar title",
      "logo": "Your navbar logo",
      "items": [
        {
          "type": "docSidebar",
          "sidebarIds": ["mySidebar"],
          "label": "Documentation",
          "position": "left"
        }
      ]
    },
    "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"
        }
      ]
  	} 
  }
}

Copied!

Optional fields

`favicon`

Type: string | undefined

Path to your site favicon; 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

{
  "favicon": "image/favicon.ico"
}

Copied!

Theme configuration

Accepted fields:

Name	Type	Default	Description
`title`	`string`	`undefined`	Title for the navbar.
`logo`	See below	`undefined`	Customization of the logo url.
`iconRedirectUrl`	`string`	`undefined`	Link to navigate to when the logo is clicked.
`items`	`NavbarItem[]`	`[]`	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

{
  "themeConfig": {
    "navbar": {
      "title": "Your site title",
      "logo": "image/logo.png"
    }
  }
}

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

{
  "themeConfig": {
    "navbar": {
      "title": "Your site title",
      "logo": "image/logo.png",
      "iconRedirectUrl": "https://docuo.io"
    }
  }
}

Copied!

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

docuo.config

{
  "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"
            }
          ]
        }
      ]
    }
  }
}

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:

Name	Type	Default	Description
`type`	`"default"`	Optional	Sets the type of this item to a link.
`label`	`string`	Required	The name to be shown for this item.
`to`	`string`	Required	Client-side routing, used for navigating within the website.
`href`	`string`	Required	A 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

{
  "themeConfig": {
    "navbar": {
      "items": [
        {
          "to": "/introduction",
          // Only one of "to" or "href" should be used
          // "href": "https://spreading.ai/blog",
          "label": "Introduction",
          "position": "left"
        }
      ]
    }
  }
}

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:

Name	Type	Default	Description
`type`	`"dropdown"`	Optional	Sets the type of this item to a dropdown.
`label`	`string`	Required	The name to be shown for this item.
`items`	`LinkLikeItem[]`	Required	The 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

{
  "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"
            }
          ]
        }
      ]
    }
  }
}

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:

Name	Type	Default	Description
`type`	`"docSidebar"`	Required	Sets the type of this navbar item to a sidebar's first document.
`sidebarIds`	`string[]`	Required	The ID list of the sidebar that this item is linked to.目前只支持设置一个 ID
`label`	`string`	First document link's sidebar label	The name to be shown for this item.
`position`	`"left" \| "right"`	`"left"`	The side of the navbar this item should appear on.
`docsInstanceId`	`string`	`"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

{
  "themeConfig": {
    "navbar": {
      "items": [
        {
          "type": "docSidebar",
          "label": "Docs",
          "sidebarIds": ["mySidebar"],
          "position": "left"
        }
      ]
    }
  }
}

Copied!

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

sidebars

{
  "mySidebar": [
    {
      "type": "autogenerated",
      "dirName": "."
    }
  ]
}

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:

Name	Type	Default	Description
`logo`	`Logo`	`undefined`	Customization of the logo url. See Navbar logo for details.
`copyright`	`string`	`undefined`	The copyright message to be displayed at the bottom.
`caption`	`string`	`undefined`	The caption message to be displayed at the bottom.
`links`	`FooterLink[]`	`[]`	The link groups to be present.
`socials`	`SocialItem[]`	`[]`	The social link groups to be present.

Example configuration:

docuo.config

{
  "themeConfig": {
    "footer": {
      "logo": "image/logo.png",
      "copyright": "xxx",
      "caption": "xxx"
    }
  }
}

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.

Name	Type	Default	Description
`title`	`string`	`undefined`	Label of the section of these links.
`items`	`FooterItem[]`	`[]`	Links in this section.

Accepted fields of each FooterItem:

Name	Type	Default	Description
`label`	`string`	Required	Text to be displayed for this link.
`to`	`string`	Required	Client-side routing, used for navigating within the website.
`href`	`string`	Required	A 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

{
  "themeConfig": {
    "footer": {
      "links": [
        {
          "title": "Product",
          "items": [
            {
              "label": "documentation",
              "to": "/"
            }
          ]
        }
      ]
    }
  }
}

Copied!

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

Example simple configuration:

docuo.config

{
  "themeConfig": {
    "footer": {
      "links": [
        {
          "label": "documentation",
          "to": "/"
        }
      ]
    }
  }
}

Copied!

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

Accepted fields of each SocialItem:

Name	Type	Default	Description
`logo`	`Logo \| DefaultSocialName`	Required	Customization of the logo url. See Navbar logo for details. Or the name of the built-in social media icon
`href`	`string`	Required	A full-page navigation, used for navigating outside of the website.

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

docuo.config

{
  "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"
        }
      ]
    }
  }
}

Copied!

Customize with json file

Overview

Required fields

`title`

`themeConfig`

Optional fields

`favicon`

Theme configuration

Navbar

Navbar logo

Navbar iconRedirectUrl

Navbar items

Footer

Footer links

Footer socials