---
title: Configuration
description: Configure your documentation with a docs.json file.
---

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

<Tabs
  values={[
    { label: 'JSON', value: 'json' },
    { label: 'YAML', value: 'yaml' },
  ]}
>
  <TabItem value="json">
  ```json title="docs.json"
  {
    "name": "My Project",
    "description": "My Project is a project that does awesome things.",
    "logo": "/assets/logo.png",
    "logoDark": "/assets/logo-dark.png"
  }
  ```
  </TabItem>
  <TabItem value="yaml">
  ```yaml title="docs.yaml"
  name: My Project
  description: My Project is a project that does awesome things.
  logo: "/assets/logo.png"
  logoDark: "/assets/logo-dark.png"
  ```
  </TabItem>
</Tabs>

## Configuration Options

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

<Property name="name" type="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.
</Property>

<hr />

<Property name="description" type="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.
</Property>

<hr />

<Property name="logo" type="string">
The path (either absolute or relative to the `/docs` directory) to the logo of your project. This will be
displayed in the header. 

<Info>Logos have a forced height of 30px.</Info>
</Property>

<hr />

<Property name="logoDark" type="string">
The path (either absolute or relative to the `/docs` directory) to the favicon of your project.
</Property>

<hr />

<Property name="socialPreview" type="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.
</Property>

<hr />

<Property name="twitter" type="string">
The Twitter handle of your project. This will be used as a page anchor and social metadata.
</Property>

<hr />

<Property name="noindex" type="string">
Whether to apply a [`noindex`](https://developers.google.com/search/docs/crawling-indexing/block-indexing) 
meta tag on every page of your project, to prevent it from showing in search engines.

<Info>When viewing a [preview](/previews), noindex will be applied by default.</Info>
</Property>

<hr />

<Property name="theme" type="string" default="#00bcd4">
The 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)`).
</Property>

<hr />

<Property name="headerDepth" type="number" default="3">
The maxium header depths to apply to the navigation menu on each page.
</Property>

<hr />

<Property name="variables" type="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:

```json
{
  "variables": {
    "versions": {
      "latest": "1.0.0",
      "next": "1.1.0"
    }
  }
}
```

Within the markdown `{{ versions.latest }}` would display `1.0.0`.

</Property>

<hr />

<Property name="googleTagManager" type="string">
If provided, the [GTM](https://tagmanager.google.com/) script with the ID will be added to each documentation webpage.
</Property>

<hr />

<Property name="googleAnalytics" type="string">
If provided, the [Google Analytics](https://analytics.google.com/analytics/web/) script with the ID will be added to each documentation webpage.
</Property>

<hr />

<Property name="zoomImages" type="boolean" default="false">
If enabled, all images will zoom when clicked by default.
</Property>

<hr />

<Property name="automaticallyDisplayName" type="boolean" default="true">
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.
</Property>

<hr />

<Property name="automaticallyInferNextPrevious" type="boolean" default="true">
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.
</Property>

<hr />

<Property name="plausibleAnalytics" type="boolean" default="false">
If set to true, the [Plausible](https://plausible.io/) analytics script will be added to each documentation webpage.

<Warning>This property will only take effect when using a [custom domain](/custom-domains).</Warning>
</Property>

<hr />

<Property name="plausibleAnalyticsScript" type="string" default="https://plausible.io/js/script.js">
If set, the self-hosted [Plausible](https://plausible.io/) analytics script will be used.

<Warning>This property will only take effect when `plausibleAnalytics` is set to `true`.</Warning>
</Property>

<hr />

<Property name="anchors" type="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).

```ts
type Anchor = {
  title: string;
  icon: string;
  link: string;
}
```

For the icons, you can use the name of any standard [Font Awesome Classic Icon](https://fontawesome.com/search?o=r&s=solid)
or [Brand Icons](https://fontawesome.com/search?o=r&f=brands), for example:
  
<Tabs
  values={[
    { label: 'JSON', value: 'json' },
    { label: 'YAML', value: 'yaml' },
  ]}
>
  <TabItem value="json">
  ```json
  {
    "anchors": [
      { title: "Homepage", icon: "house", link: "https://example.com" }
    ]
  }
  ```
  </TabItem>
  <TabItem value="yaml">
  ```yaml
  anchors:
  - title: "Homepage"
    link: "https://example.com"
    icon: "house"
  ```
  </TabItem>
</Tabs>
</Property>

<hr />

<Property name="docsearch" type="object">
An object containing the details of your [DocSearch](https://docsearch.algolia.com/) account. This will enable
a search bar at the top of the page. Note, all properies must be provided.

<Tabs
  values={[
    { label: 'JSON', value: 'json' },
    { label: 'YAML', value: 'yaml' },
  ]}
>
  <TabItem value="json">
  ```json title="Example DocSearch config"
  {
    "docsearch": {
      "appId": "R2IYF7ETH7",
      "apiKey": "599cec31baffa4868cae4e79f180729b",
      "indexName": "docsearch"
    }
  }
  ```
  </TabItem>
  <TabItem value="yaml">
  ```yaml title="Example DocSearch config"
  docsearch:
    appId: R2IYF7ETH7
    apiKey: 599cec31baffa4868cae4e79f180729b
    indexName: docsearch
  ```
  </TabItem>
</Tabs>
</Property>

<hr />

<Property name="sidebar" type="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.

```ts
type Sidebar = [
  string,
  string | [string, string][]
][];
```

<Tabs
  values={[
    { label: 'JSON', value: 'json' },
    { label: 'YAML', value: 'yaml' },
  ]}
>
  <TabItem value="json">
  ```json
  {
    "sidebar": [
      ["Getting Started", "/"],
      ["Advanced", [
        ["Reference API", "/reference"],
        ["FAQs", "/faqs"]
      ]]
    ]
  }
  ```
  </TabItem>
  <TabItem value="yaml">
  ```yaml
  sidebar:
  - - Getting Started
    - "/"
  - - Advanced
    - - - Reference API
        - "/reference"
      - - FAQs
        - "/faqs"
  ```
  </TabItem>
</Tabs>


<Info>View the [locales](/locales) documentation for more details.</Info>
</Property>

export const Property = (props) => (
  <div>
    <div style={{ display: 'flex', alignItems: 'center' }}>
      <div style={{ flexGrow: 1 }}>
        <code className="text-docs-theme" style={{ fontSize: 16 }}>{props.name}</code>
        {!!props.default && <span style={{ paddingLeft: 8 }}>Default: <code>{props.default}</code></span>}
      </div>
      <div>
        <span className="font-mono">{props.type}</span>
      </div>
    </div>
    <div>{props.children}</div>
  </div>
);