Configuration

The default docs.page configuration is designed to display a minimal documentation website for your project. Adding a configuration file enables you to customize the look and feel, along with adding some additional functionality to improve the overall experience of browsing the documentation.

You can configure your documentation by adding a docs.json file to the root of your repository.

Options

Each option undergoes validation, and any invalid value passed will be removed.

name

The name of the project. If provided, the name is displayed in a few places throughout the website such as the meta title and website header.

logo

The URL or local repository path to the project logo. If provided, will be used as the favicon and will be displayed in the header.

logoDark

The URL or local repository path to the project logo. If provided, will be displayed in the header when Dark Mode is currently enabled.

favicon

The URL or local repository path to the project favicon. If omitted, the docs.page favicon will be displayed.

socialPreview

The URL to the social preview image, used when a URL to the documentation is being shared on social media platforms or Open Graph. Images should be at least 640×320px (1280×640px for best display).

twitter

A Twitter username handle. If provided, a Twitter logo will be placed in the header of the website.

noindex

Whether or not the website should be indexed. By default, documentation websites are not indexed if a project config file is not found.

To learn more about indexing, view the Advanced documentation.

theme

A color used throughout the website on anchor tags, search and for general highlighting usage. It is recommended that the color is vibrant/light. The provided value must be parsable by the color library.

docsearch

If provided, the docsearch value should be an object containing your apiKey and indexName for your DocSearch instance. If the appId is provided, a pre-connection to the Algolia database instance will be established which should help speed up initial search times users with slow connections.

To learn more, join the DocSearch program.

For example:

{
  "docsearch": {
    "appId": "...",
    "apiKey": "...",
    "indexName": "awesome-project"
  }
}

automaticallyInferNextPrevious

A boolean indicating if the next and previous links should be automatically inferred from the sidebar configuration. You can still overwrite a specific link by providing the next and previous keys in the frontmatter.

sidebar

An array containing nested sidebar array items. If provided, will be rendered on every page down the left hand side.

A sidebar item can contain an array with two string values, or an array where the first string value is a title and the second value is an array with two string values.

For example, the following will create a sidebar with a single link and nested expandable sidebar:

{
  "sidebar": [
    ["Example", "/example"],
    ["Section Title", [["Nested Title", "/nested-example"]]]
  ]
}

headerDepth

A number representing how deep headers remain important. Headers within the depth will be shown on the table of contents. All "h1" tags are ignored.

For example, a depth of 4 will handle h2, h3 & h4 tags.

variables

A deeply nested object which contains values which can be injected on any documentation page. This is useful for projects which have repetitive common values (such a versions) which should be reflected consistently across all pages.

The lodash.get utility is used to extract in-page variables from the provided object.

Example:

{
  "variables": {
    "versions": {
      "alpha": "3.0.0-alpha.1",
      "beta": "3.0.0-beta.1",
      "current": "2.9.12"
    }
  }
}

Within your Markdown, provide the dot-notated path to the variable (e.g versions.alpha) surrounded by {{ }} brackets.

googleTagManager

If provided, Google Tag Manager will be added to all of your documentation pages. Tags should start with GTM-.

googleAnalytics

If provided, Google Analytics will be added to all of your documentation pages.

zoomImages

A boolean value representing whether images are zoomable by default.

Note; If using the <Image /> component, the zoom property provided will override this value.