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.
Key | Type | Default |
---|---|---|
name | string |
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.
Key | Type | Default |
---|---|---|
logo | string |
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.
Key | Type | Default |
---|---|---|
logoDark | string |
favicon
The URL or local repository path to the project favicon. If omitted, the docs.page favicon will be displayed.
Key | Type | Default |
---|---|---|
favicon | string |
twitter
A Twitter username handle. If provided, a Twitter logo will be placed in the header of the website.
Key | Type | Default |
---|---|---|
twitter | string |
noindex
Whether or not the website should be indexed. By default, documentation websites are not indexed if a project config file is not found.
Key | Type | Default |
---|---|---|
noindex | boolean | false |
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.
Key | Type | Default |
---|---|---|
theme | string | '#00bcd4' |
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.
Key | Type | Default |
---|---|---|
docsearch | DocSearch |
DocSearch | Type | Default |
---|---|---|
appId | string | |
apiKey | string | |
indexName | string |
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.
Key | Type | Default |
---|---|---|
automaticallyInferNextPrevious | boolean | true |
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.
Key | Type | Default |
---|---|---|
headerDepth | number | 3 |
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.
Key | Type | Default |
---|---|---|
variables | 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-
.
Key | Type | Default |
---|---|---|
googleTagManager | string |
googleAnalytics
If provided, Google Analytics will be added to all of your documentation pages.
Key | Type | Default |
---|---|---|
googleAnalytics | string |
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.
Key | Type | Default |
---|---|---|
zoomImages | boolean | false |
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).
socialPreview
string