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:

Configuration Options#

Below is a list of all available configuration options, their type and default values.

name

string

The 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.

description

string

The 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.

logo

string

The path (either absolute or relative to the /docs directory) to the logo of your project. This will be displayed in the header.

Logos have a forced height of 30px.

logoDark

string

The path (either absolute or relative to the /docs directory) to the favicon of your project.

socialPreview

string

The 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.

twitter

string

The Twitter handle of your project. This will be used as a page anchor and social metadata.

noindex

string

Whether to apply a noindex meta tag on every page of your project, to prevent it from showing in search engines.

When viewing a preview, noindex will be applied by default.

themeDefault: #00bcd4

string

The theme of your project, applied to active links and other subtle places. This color should 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: 3

number

The maxium header depths to apply to the navigation menu on each page.

variables

object

Any 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.

googleTagManager

string

If provided, the GTM script with the ID will be added to each documentation webpage.

googleAnalytics

string

If provided, the Google Analytics script with the ID will be added to each documentation webpage.

zoomImagesDefault: false

boolean

If enabled, all images will zoom when clicked by default.

automaticallyDisplayNameDefault: true

boolean

If 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: true

boolean

If 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: false

boolean

If set to true, the Plausible analytics script will be added to each documentation webpage.

This property will only take effect when using a custom domain.

plausibleAnalyticsScriptDefault: https://plausible.io/js/script.js

string

If set, the self-hosted Plausible analytics script will be used.

This property will only take effect when plausibleAnalytics is set to true.

anchors

Anchor[]

When 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:

docsearch

object

An 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.

sidebar

Array<Sidebar> | Record<string, Sidebar>

This 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][]][];

View the locales documentation for more details.