docusaurus.config.js

info

Refer to the Getting Started Configuration for examples.

Overview

docusaurus.config.js contains configurations for your site and is placed in the root directory of your site.

note

With a TypeScript Docusaurus codebase your config file may be called docusaurus.config.ts. The syntax is broadly identical to the js config file with the addition of types. You can see an example on the Docusaurus Website itself.

This file is run in Node.js and should export a site configuration object, or a function that creates it.

The docusaurus.config.js file supports:

• ES Modules
• CommonJS
• TypeScript

Examples:

docusaurus.config.js

export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
};

docusaurus.config.js

export default async function createConfigAsync() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // your site config ...
  };
}

tip

Refer to Syntax to declare docusaurus.config.js for a more exhaustive list of examples and explanations.

Required fields

title

• Type: string

Title for your website. Will be used in metadata and as browser tab title.

docusaurus.config.js

export default {
  title: 'Docusaurus',
};

url

• Type: string

URL for your website. This can also be considered the top-level hostname. For example, https://facebook.github.io is the URL of https://facebook.github.io/metro/, and https://docusaurus.io is the URL for https://docusaurus.io. This field is related to the baseUrl field.

docusaurus.config.js

export default {
  url: 'https://docusaurus.io',
};

Special case for i18n sites

If your site uses multiple locales, it is possible to provide a distinct url for each locale thanks to the siteConfig.i18n.localeConfigs[<locale>].url attribute. This makes it possible to deploy a localized Docusaurus site over multiple domains.

baseUrl

• Type: string

The base URL of your site is the path segment appearing just after the url, letting you eventually host your site under a subpath instead of at the root of the domain.

For example, let's consider you want to host a site at https://facebook.github.io/metro/, then you must configure it accordingly:

• url should be 'https://facebook.github.io'
• baseUrl should be '/metro/'

By default, a Docusaurus site is hosted at the root of the domain:

docusaurus.config.js

export default {
  baseUrl: '/',
};

Special case for i18n sites

If your site uses multiple locales, then Docusaurus will automatically localize the baseUrl of your site based on smart heuristics:

• For the default locale, baseUrl will be /<siteBaseUrl>/
• For other locales, baseUrl will be /<siteBaseUrl>/<locale>/
• When building a single locale at a time (with docusaurus build --locale <locale>), baseUrl will be /<siteBaseUrl>/, assuming the intent is to deploy each locale on distinct domains.

When the localized baseUrl Docusaurus computes doesn't satisfy you, it's always possible to override it by providing an explicit localized baseUrl thanks to the siteConfig.i18n.localeConfigs[<locale>].baseUrl attribute.

Optional fields

favicon

• Type: string | undefined

Path to your site favicon; must be a URL that can be used in link's href. For example, if your favicon is in static/img/favicon.ico:

docusaurus.config.js

export default {
  favicon: '/img/favicon.ico',