Configuration
Check the docusaurus.config.js API reference for an exhaustive list of options.
Docusaurus has a unique take on configurations. We encourage you to congregate information about 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 to be able to focus on documentation while still being able to customize the site.
Syntax to declare docusaurus.config.js
The docusaurus.config.js file is run in Node.js and should export either:
- a config object
- a function that creates the config object
The docusaurus.config.js file only supports the CommonJS module system:
- Required: use
module.exports = /* your config*/to export your Docusaurus config - Optional: use
require("lib")to import Node.js packages - Optional: use
await import("lib")(dynamic import) in an async function to import ESM-Only Node.js packages
Node.js gives us the ability to declare our Docusaurus configuration in various equivalent ways, and all the following config examples lead to the exact same result:
module.exports = {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
const config = {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
module.exports = config;
module.exports = function configCreator() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
};
module.exports = async function createConfigAsync() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
};
Using an async config creator can be useful to import ESM-only modules (notably most Remark plugins). It is possible to import such modules thanks to dynamic imports:
module.exports = async function createConfigAsync() {
// Use a dynamic import instead of require('esm-lib')
const lib = await import('lib');
return {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// rest of your site config...
};
};
What goes into a docusaurus.config.js?
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:
Site metadata
Site metadata contains the essential global metadata such as title, url, baseUrl, and favicon.
They are used in several 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, organizationName, and optionally deploymentBranch 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 themes, plugins, and presets for your site in the themes, plugins, and presets fields, respectively. These are typically npm packages:
module.exports = {
// ...
plugins: [
'@docusaurus/plugin-content-blog',
'@docusaurus/plugin-content-pages',
],
themes: ['@docusaurus/theme-classic'],
};
Docusaurus supports module shorthands, allowing you to simplify the above configuration as:
module.exports = {
// ...
plugins: ['content-blog', 'content-pages'],
themes: ['classic'],
};
They can also be loaded from local directories:
const path = require('path');
module.exports = {
// ...
themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};
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:
module.exports = {
// ...
plugins: [
[
'content-blog',
{
path: 'blog',
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
// ...
},
],
'content-pages',
],
};
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.
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
},
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
},
],
],
};
The presets: [['classic', {...}]] shorthand works as well.
For further help configuring themes, plugins, and presets, see Using Plugins.
Custom configurations
Docusaurus guards docusaurus.config.js from unknown fields. To add custom fields, define them in customFields.
Example:
module.exports = {
// ...
customFields: {
image: '',
keywords: [],
},
// ...
};
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:
import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
const Hello = () => {
const {siteConfig} = useDocusaurusContext();
const {title, tagline} = siteConfig;
return <div>{`${title} · ${tagline}`}</div>;
};
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.
Customizing Babel Configuration
For new Docusaurus projects, we automatically generated a babel.config.js in the project root.
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
Most of the time, this configuration will work just fine. If you want to customize your Babel configuration (e.g. to add support for Flow), you can directly edit this file. For your changes to take effect, you need to restart the Docusaurus dev server.