Customize with json file
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:
{
"title": "Your site title",
"favicon": "Your site favicon"
}
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.
{
"title": "Your site title"
}
themeConfig
- Type:
Object
The theme configuration object to customize your site UI like navbar and footer.
Example:
{
"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
}
}
}
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
:
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.
{
"favicon": "image/favicon.ico"
}
Remove watermarks
- Type:
boolean
- Default:
false
You can set whether to remove Docuo watermark on your published website pages via themeConfig.removeWatermark
. The default setting is false
, which means keeping watermarks. You need to set it to true
if you want to remove the watermarks.
Example configuration:
{
"themeConfig": {
"removeWatermark": true
}
}
Removing Docuo watermark requires Startup or Enterprise plan. If your current plan is "Free", you need to make an update.
Theme configuration
Navbar
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. |
Navbar logo
The logo can be placed in static folder.
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:
{
"themeConfig": {
"navbar": {
"title": "Your site title",
"logo": "image/logo.png"
}
}
}
If your website has configured dark mode
and you have another logo for dark mode
, you can also configure logo like this:
{
"themeConfig": {
"navbar": {
"title": "Your site title",
"logo": {
"light": "image/logo_light.png",
"dark": "image/logo_dark.png"
}
}
}
}
Navbar iconRedirectUrl
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:
{
"themeConfig": {
"navbar": {
"title": "Your site title",
"logo": "image/logo.png",
"iconRedirectUrl": "https://docuo.io"
}
}
}
Navbar items
You can add items to the navbar using themeConfig.navbar.items
.
{
"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"
}
]
}
]
}
}
}
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:
{
"themeConfig": {
"navbar": {
"items": [
{
"to": "/introduction",
"label": "Introduction",
"position": "left"
}
]
}
}
}
- 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:
{
"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"
}
]
}
]
}
}
}
- 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. |
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. |
Use this navbar item type if your sidebar is updated often and the order is not stable.
Example configuration:
{
"themeConfig": {
"navbar": {
"items": [
{
"type": "docSidebar",
"label": "Docs",
"sidebarIds": ["mySidebar"],
"position": "left"
}
]
}
}
}
The sidebarId
of the navbar item corresponds to one of the sidebar keys, which is "mySidebar".
{
"mySidebar": [
{
"type": "autogenerated",
"dirName": "."
}
]
}
Footer
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.
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 |
---|---|---|---|
hidden | boolean | false | Whether to hide footer. |
logo | Logo | undefined | Customization of the logo url. See Navbar logo for details. |
logoUrl | string | undefined | Link to navigate to when the logo is clicked. |
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:
{
"themeConfig": {
"footer": {
"logo": "image/logo.png",
"copyright": "xxx",
"caption": "xxx"
}
}
}
If your website has configured dark mode
and you have another logo for dark mode
, you can also configure your footer logo like this:
{
"themeConfig": {
"footer": {
"logo": {
"light": "image/logo_light.png",
"dark": "image/logo_dark.png"
}
}
}
}
Footer links
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 FooterItem
s 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:
{
"themeConfig": {
"footer": {
"links": [
{
"title": "Product",
"items": [
{
"label": "documentation",
"to": "/"
}
]
}
]
}
}
}
A simple footer just has a list of FooterItem
s displayed in a row.
Example simple configuration:
{
"themeConfig": {
"footer": {
"links": [
{
"label": "documentation",
"to": "/"
}
]
}
}
}
Footer socials
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”
{
"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"
}
]
}
}
}
Color mode
You can customize your color mode within the colorMode
object.
Accepted fields:
Name | Type | Default | Description |
---|---|---|---|
defaultMode | 'light' | 'dark' | 'system' | 'light' | The color mode when user first visits the site. |
disableSwitch | boolean | false | Hides the switch in the navbar. Useful if you want to support a single color mode. |
Example configuration:
{
"themeConfig": {
"colorMode": {
"defaultMode": "light",
"disableSwitch": false
}
}
}
Primary Colors
You can customize your primary colors within the colors
object.
Accepted fields:
Name | Type | Default | Description |
---|---|---|---|
primaryLight | string | '#1ABD00' | Primary color for highlighted content in light mode. |
primaryDark | string | '#05EC07' | Primary color for highlighted content in dark mode. |
Example configuration:
{
"themeConfig": {
"colors": {
"primaryLight": "#1ABD00",
"primaryDark": "#05EC07"
}
}
}