Configuration
Docusaurus has a unique take on configurations. We encourage you to congregate information of your site into one place. We guard the fields of this file, and facilitate making this data object accessible across your site.
Keeping a well-maintained docusaurus.config.js
helps you, your collaborators, and your open source contributors be able to focus on documentation while still being able to customize the site.
docusaurus.config.js
?
What goes into a You should not have to write your docusaurus.config.js
from scratch even if you are developing your site. All templates come with a docusaurus.config.js
that includes defaults for the common options.
However, it can be helpful if you have a high-level understanding of how the configurations are designed and implemented.
The high-level overview of Docusaurus configuration can be categorized into:
For exact reference to each of the configurable fields, you may refer to docusaurus.config.js
API reference.
Site metadata
Site metadata contains the essential global metadata such as title
, url
, baseUrl
and favicon
.
They are used in a number of places such as your site's title and headings, browser tab icon, social sharing (Facebook, Twitter) information or even to generate the correct path to serve your static files.
Deployment configurations
Deployment configurations such as projectName
and organizationName
are used when you deploy your site with the deploy
command.
It is recommended to check the deployment docs for more information.
Theme, plugin, and preset configurations
List the theme, plugins, and presets for your site in the themes
, plugins
, and presets
fields, respectively. These are typically npm packages:
They can also be loaded from local directories:
To specify options for a plugin or theme, replace the name of the plugin or theme in the config file with an array containing the name and an options object:
To specify options for a plugin or theme that is bundled in a preset, pass the options through the presets
field. In this example, docs
refers to @docusaurus/plugin-content-docs
and theme
refers to @docusaurus/theme-classic
.
For further help configuring themes, plugins, and presets, see Using Themes, Using Plugins, and Using Presets.
Custom configurations
Docusaurus guards docusaurus.config.js
from unknown fields. To add custom fields, define them in customFields
.
Example:
Accessing configuration from components
Your configuration object will be made available to all the components of your site. And you may access them via React context as siteConfig
.
Basic example:
tip
If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in docusaurus.config.js
.