docusaurus.config.js

Overview ​

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

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:

Examples:

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

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

Required fields ​

title ​

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

export default {
  title: 'Docusaurus',
};

url ​

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.

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

baseUrl ​

Base URL for your site. Can be considered as the path after the host. For example, /metro/ is the base URL of https://facebook.github.io/metro/ . For URLs that have no path, the baseUrl should be set to / . This field is related to the url field. Always has both leading and trailing slash.

export default {
  baseUrl: '/',
};

Optional fields ​

favicon ​

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 :

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

trailingSlash ​

Allow to customize the presence/absence of a trailing slash at the end of URLs/links, and how static HTML files are generated:

i18n ​

The i18n configuration object to localize your site .

Example:

export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fa'],
    path: 'i18n',
    localeConfigs: {
      en: {
        label: 'English',
        direction: 'ltr',
        htmlLang: 'en-US',
        calendar: 'gregory',
        path: 'en',
      },
      fa: {
        label: 'فارسی',
        direction: 'rtl',
        htmlLang: 'fa-IR',
        calendar: 'persian',
        path: 'fa',
      },
    },
  },
};

noIndex ​

This option adds <meta name="robots" content="noindex, nofollow"> to every page to tell search engines to avoid indexing your site (more information here ).

Example:

export default {
  noIndex: true, // Defaults to `false`
};

onBrokenLinks ​

The behavior of Docusaurus when it detects any broken link.

By default, it throws an error, to ensure you never ship any broken link, but you can lower this security if needed.

onBrokenMarkdownLinks ​

The behavior of Docusaurus when it detects any broken Markdown link.

By default, it prints a warning, to let you know about your broken Markdown link, but you can change this security if needed.

onDuplicateRoutes ​

The behavior of Docusaurus when it detects any duplicate routes .

By default, it displays a warning after you run yarn start or yarn build .

tagline ​

The tagline for your website.

export default {
  tagline:
    'Docusaurus makes it easy to maintain Open Source documentation websites.',
};

organizationName ​

The GitHub user or organization that owns the repository. You don't need this if you are not using the docusaurus deploy command.

export default {
  // Docusaurus' organization is facebook
  organizationName: 'facebook',
};

projectName ​

The name of the GitHub repository. You don't need this if you are not using the docusaurus deploy command.

export default {
  projectName: 'docusaurus',
};

deploymentBranch ​

The name of the branch to deploy the static files to. You don't need this if you are not using the docusaurus deploy command.

export default {
  deploymentBranch: 'gh-pages',
};

githubHost ​

The hostname of your server. Useful if you are using GitHub Enterprise. You don't need this if you are not using the docusaurus deploy command.

export default {
  githubHost: 'github.com',
};

githubPort ​

The port of your server. Useful if you are using GitHub Enterprise. You don't need this if you are not using the docusaurus deploy command.

export default {
  githubPort: '22',
};

themeConfig ​

The theme configuration object to customize your site UI like navbar and footer.

Example:

plugins ​

type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any];

See plugin method references for the shape of a PluginModule .

export default {
  plugins: [
    'docusaurus-plugin-awesome',
    ['docusuarus-plugin-confetti', {fancy: false}],
    () => ({
      postBuild() {
        console.log('Build finished');
      },
    }),
  ],
};

themes ​

export default {
  themes: ['@docusaurus/theme-classic'],
};

presets ​

type PresetConfig = string | [string, any];

export default {
  presets: [],
};

markdown ​

The global Docusaurus Markdown config.

type MarkdownPreprocessor = (args: {
  filePath: string;
  fileContent: string;
}) => string;

type MDX1CompatOptions =
  | boolean
  | {
      comments: boolean;
      admonitions: boolean;
      headingIds: boolean;
    };

type MarkdownConfig = {
  format: 'mdx' | 'md' | 'detect';
  mermaid: boolean;
  preprocessor?: MarkdownPreprocessor;
  mdx1Compat: MDX1CompatOptions;
};

Example:

export default {
  markdown: {
    format: 'mdx',
    mermaid: true,
    preprocessor: ({filePath, fileContent}) => {
      return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
    },
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
  },
};

customFields ​

Docusaurus guards docusaurus.config.js from unknown fields. To add a custom field, define it on customFields .

export default {
  customFields: {
    admin: 'endi',
    superman: 'lol',
  },
};

Attempting to add unknown fields in the config will lead to errors during build time:

Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js

staticDirectories ​

An array of paths, relative to the site's directory or absolute. Files under these paths will be copied to the build output as-is.

Example:

export default {
  staticDirectories: ['static'],
};

headTags ​

An array of tags that will be inserted in the HTML <head> . The values must be objects that contain two properties; tagName and attributes . tagName must be a string that determines the tag being created; eg "link" . attributes must be an attribute-value map.

Example:

export default {
  headTags: [
    {
      tagName: 'link',
      attributes: {
        rel: 'icon',
        href: '/img/docusaurus.png',
      },
    },
  ],
};

This would become <link rel="icon" href="img/docusaurus.png" /> in the generated HTML.

scripts ​

An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The <script> tags will be inserted in the HTML <head> . If you use a plain object, the only required attribute is src , and any other attributes are permitted (each one should have boolean/string values).

Note that <script> added here are render-blocking, so you might want to add async: true / defer: true to the objects.

Example:

export default {
  scripts: [
    // String format.
    'https://docusaurus.io/script.js',
    // Object format.
    {
      src: 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',
      async: true,
    },
  ],
};

stylesheets ​

An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The <link> tags will be inserted in the HTML <head> . If you use an object, the only required attribute is href , and any other attributes are permitted (each one should have boolean/string values).

Example:

export default {
  stylesheets: [
    // String format.
    'https://docusaurus.io/style.css',
    // Object format.
    {
      href: 'http://mydomain.com/style.css',
    },
  ],
};

clientModules ​

An array of client modules to load globally on your site.

Example:

export default {
  clientModules: ['./mySiteGlobalJs.js', './mySiteGlobalCss.css'],
};

ssrTemplate ​

An HTML template written in Eta's syntax that will be used to render your application. This can be used to set custom attributes on the body tags, additional meta tags, customize the viewport , etc. Please note that Docusaurus will rely on the template to be correctly structured in order to function properly, once you do customize it, you will have to make sure that your template is compliant with the requirements from upstream.

Example:

export default {
  ssrTemplate: `<!DOCTYPE html>
<html <%~ it.htmlAttributes %>>
  <head>
    <meta charset="UTF-8">
    <meta name="generator" content="Docusaurus v<%= it.version %>">
    <% it.metaAttributes.forEach((metaAttribute) => { %>
      <%~ metaAttribute %>
    <% }); %>
    <%~ it.headTags %>
    <% it.stylesheets.forEach((stylesheet) => { %>
      <link rel="stylesheet" href="<%= it.baseUrl %><%= stylesheet %>" />
    <% }); %>
    <% it.scripts.forEach((script) => { %>
      <link rel="preload" href="<%= it.baseUrl %><%= script %>" as="script">
    <% }); %>
  </head>
  <body <%~ it.bodyAttributes %>>
    <%~ it.preBodyTags %>
    <div id="__docusaurus">
      <%~ it.appHtml %>
    </div>
    <% it.scripts.forEach((script) => { %>
      <script src="<%= it.baseUrl %><%= script %>"></script>
    <% }); %>
    <%~ it.postBodyTags %>
  </body>
</html>`,
};

titleDelimiter ​

Will be used as title delimiter in the generated <title> tag.

Example:

export default {
  titleDelimiter: '🦖', // Defaults to `|`
};

baseUrlIssueBanner ​

When enabled, will show a banner in case your site can't load its CSS or JavaScript files, which is a very common issue, often related to a wrong baseUrl in site config.

Example:

export default {
  baseUrlIssueBanner: true, // Defaults to `true`
};