Configuration
You can heavily customize your documentation by providing a configuration file at the root of your GitHub repository. The configuration file syntax supports JSON or YAML.
If no configuration file is provided, or one of the properties is invalid a default value will be provided instead (see below for details).
Getting Started
Add a docs.json or docs.yaml file to the root of your repository. Below is a list of all
available configuration options, which can be used to modify the logos, theme, analytics and more. For example
a basic configuration might look like:
{
"name": "My Project",
"description": "My Project is a project that does awesome things.",
"logo": "/assets/logo.png",
"logoDark": "/assets/logo-dark.png"
}
Configuration Options
Below is a list of all available configuration options, their type and default values.
nameThe name of your project. This will be displayed in the header of the website. If not provided, the GitHub repository name will be used instead.
descriptionThe description of your project. This will be used for website metadata (e.g. social tags) if provided. If a page frontmatter description is provided, it will be used instead.
logoThe path (either absolute or relative to the /docs directory) to the logo of your project. This will be
displayed in the header.
logoDarkThe path (either absolute or relative to the /docs directory) to the favicon of your project.
socialPreviewThe path (either absolute or relative to the /docs directory) to social preview card which will be displayed
when linked on social media (e.g. Twitter). If page frontmatter provides a social card, it will be used instead.
If not provided, a card will be automatically generated for you.
twitterThe Twitter handle of your project. This will be used as a page anchor and social metadata.
noindexthemeDefault: #00bcd4The theme of your project, applied to active links and other subtle places. This should color be visible on
both dark and light modes. Can either be a hex color (e.g. #00bcd4) or a RGB (e.g. rgb(0,188,212)).
headerDepthDefault: 3The maxium header depths to apply to the navigation menu on each page.
variablesAny variables to apply to the markdown pages. When providing a variable within mustache syntax (e.g. {{ variable }}),
it will be replaced with the value provided here. For example:
{
"variables": {
"versions": {
"latest": "1.0.0",
"next": "1.1.0"
}
}
}
Within the markdown {{ versions.latest }} would display 1.0.0.
googleTagManagerIf provided, the GTM script with the ID will be added to each documentation webpage.
googleAnalyticsIf provided, the Google Analytics script with the ID will be added to each documentation webpage.
zoomImagesDefault: falseIf enabled, all images will zoom when clicked by default.
automaticallyDisplayNameDefault: trueIf enabled, the name of your project (or repository name) will be automatically displayed in the header,
next to the logo. Set to false to only show a logo.
automaticallyInferNextPreviousDefault: trueIf true, the next and previous links will be automatically inferred from the sidebar menu.
If frontmatter next/previous links are provided on a page level, they will be used instead.
plausibleAnalyticsDefault: falseIf set to true, the Plausible analytics script will be added to each documentation webpage.
plausibleAnalyticsScriptDefault: https://plausible.io/js/script.jsIf set, the self-hosted Plausible analytics script will be used.
plausibleAnalytics is set to true.anchorsWhen provided, the anchors will be displayed above the sidebar menu. These are useful for important links which persist across your documentation (e.g. homepage, CTA buttons etc).
type Anchor = {
title: string;
icon: string;
link: string;
}
For the icons, you can use the name of any standard Font Awesome Classic Icon or Brand Icons, for example:
{
"anchors": [
{ title: "Homepage", icon: "house", link: "https://example.com" }
]
}
docsearchAn object containing the details of your DocSearch account. This will enable a search bar at the top of the page. Note, all properies must be provided.
{
"docsearch": {
"appId": "R2IYF7ETH7",
"apiKey": "599cec31baffa4868cae4e79f180729b",
"indexName": "docsearch"
}
}
sidebarThis property allows you to render sidebar links to navigate around your documentation. It can either be an array/list of links, or an object where the key is a locale identifier and the value the sidebar links for that locale.
The sidebar only supports a single level of nesting.
type Sidebar = [
string,
string | [string, string][]
][];
{
"sidebar": [
["Getting Started", "/"],
["Advanced", [
["Reference API", "/reference"],
["FAQs", "/faqs"]
]]
]
}