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.

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

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.

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.

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

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

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

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

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.

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.

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"
  }
}

An array of navigation items. If provided, the links will be displayed in the website header.

The fist item of an item is the title, and the second item is a URL, for example:

{
  "navigation": [
    ["Example", "/example"],
    ["External", "https://google.com"]
  ]
}

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 another nested array (which will be displayed as an expandable list).

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

{
  "navigation": [
    ["Example", "/example"],
    [
      "Expandable",
      [
        ["Nested Example", "/example-nested"],
        ["Nested Expandable", [["Nested x2 Example", "/example-nested-x2"]]]
      ]
    ]
  ]
}

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.

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.

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

A boolean value representing whether images are zoomable by default.

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