Version: 2.0.0-beta.4

Theme configuration

This configuration applies to all main themes.

Common#

Color mode - dark mode#

The classic theme provides by default light and dark mode support, with a navbar switch for the user.

It is possible to customize the color mode support with the following configuration:

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    // ...    colorMode: {      // "light" | "dark"      defaultMode: 'light',
      // Hides the switch in the navbar      // Useful if you want to support a single color mode      disableSwitch: false,
      // Should we use the prefers-color-scheme media-query,      // using user system preferences, instead of the hardcoded defaultMode      respectPrefersColorScheme: false,
      // Dark/light switch icon options      switchConfig: {        // Icon for the switch while in dark mode        darkIcon: '🌙',
        // CSS to apply to dark icon,        // React inline style object        // see https://reactjs.org/docs/dom-elements.html#style        darkIconStyle: {          marginLeft: '2px',        },
        // Unicode icons such as '\u2600' will work        // Unicode with 5 chars require brackets: '\u{1F602}'        lightIcon: '\u{1F602}',
        lightIconStyle: {          marginLeft: '1px',        },      },    },    // ...  },  // ...};

caution

With respectPrefersColorScheme: true, the defaultMode is overridden by user system preferences.

If you only want to support one color mode, you likely want to ignore user system preferences.

Meta image#

You can configure a default image that will be used for your meta tag, in particular og:image and twitter:image.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    // Relative to your site's "static" directory.    // Cannot be SVGs. Can be external URLs too.    image: 'img/docusaurus.png',    // ...  },};

Metadatas#

You can configure additional html metadatas (and override existing ones).

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    metadatas: [{name: 'twitter:card', content: 'summary'}],    // ...  },};

Announcement bar#

Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and optionally dismissable panel above the navbar.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    announcementBar: {      id: 'support_us', // Any value that will identify this message.      content:        'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>',      backgroundColor: '#fafbfc', // Defaults to `#fff`.      textColor: '#091E42', // Defaults to `#000`.      isCloseable: false, // Defaults to `true`.    },    // ...  },};

i18n#

Read the i18n introduction first.

Translation files location#

Base path: website/i18n/<locale>/docusaurus-theme-<themeName>
Multi-instance path: N/A
JSON files: extracted with docusaurus write-translations
Markdown files: N/A

Example file-system structure#

website/i18n/<locale>/docusaurus-theme-classic││ # translations for the theme├── navbar.json└── footer.json

Hooks#

`useThemeContext`#

React hook to access theme context. This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use.

Usage example:

import React from 'react';import useThemeContext from '@theme/hooks/useThemeContext';
const Example = () => {  const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext();
  return <h1>Dark mode is now {isDarkTheme ? 'on' : 'off'}</h1>;};

note

The component calling useThemeContext must be a child of the Layout component.

function ExamplePage() {  return (    <Layout>      <Example />    </Layout>  );}

Navbar#

Navbar title & logo#

You can add a logo and title to the navbar via themeConfig.navbar. Logo can be placed in static folder. Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab.

To improve dark mode support, you can also set a different logo for this mode.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    navbar: {      title: 'Site Title',      logo: {        alt: 'Site Logo',        src: 'img/logo.svg',        srcDark: 'img/logo_dark.svg', // Default to `logo.src`.        href: 'https://docusaurus.io/', // Default to `siteConfig.baseUrl`.        target: '_self', // By default, this value is calculated based on the `href` attribute (the external link will open in a new tab, all others in the current one).      },    },    // ...  },};

Navbar items#

You can add items to the navbar via themeConfig.navbar.items.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    navbar: {      items: [        {          type: 'doc',          position: 'left',          docId: 'introduction',          label: 'Docs',        },        {to: 'blog', label: 'Blog', position: 'left'},        {          type: 'docsVersionDropdown',          position: 'right',        },        {          type: 'localeDropdown',          position: 'right',        },        {          href: 'https://github.com/facebook/docusaurus',          position: 'right',          className: 'header-github-link',          'aria-label': 'GitHub repository',        },      ],    },    // ...  },};

The items can have different behaviors based on the type field. The sections below will introduce you to all the types of navbar items available.

Navbar link#

By default, Navbar items are regular links (internal or external).

React Router should automatically apply active link styling to links, but you can use activeBasePath in edge cases. For cases in which a link should be active on several different paths (such as when you have multiple doc folders under the same sidebar), you can use activeBaseRegex. activeBaseRegex is a more flexible alternative to activeBasePath and takes precedence over it -- Docusaurus parses it into a regular expression that is tested against the current URL.

Outbound (external) links automatically get target="_blank" rel="noopener noreferrer" attributes.

Accepted fields:

Field	Value	Explanation	Required	Default
`label`	`string`	The name to be shown for this item.	Yes
`to`	`string`	Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value.	Yes
`href`	`string`	A full-page navigation, used for navigating outside of the website. Only one of `to` or `href` should be used.	Yes
`prependBaseUrlToHref`	`boolean`	Prepends the baseUrl to `href` values.	No	`false`
`position`	`'left' \| 'right'`	The side of the navbar this item should appear on.	No	`'left'`
`activeBasePath`	`string`	To apply the active class styling on all routes starting with this path. This usually isn't necessary.	No	`to` / `href`
`activeBaseRegex`	`string`	Alternative to `activeBasePath` if required.	No	`undefined`
`className`	`string`	Custom CSS class (for styling any item).	No	`''`

Example configuration:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          to: 'docs/introduction',          // Only one of "to" or "href" should be used          // href: 'https://www.facebook.com',          label: 'Introduction',          position: 'left',          activeBaseRegex: 'docs/(next|v8)',        },      ],    },  },};

Navbar dropdown#

Navbar items of the type dropdown has the additional items field, an inner array of navbar items.

Navbar dropdown items only accept the following "link-like" item types:

Navbar link
Navbar doc link
Navbar doc version

Note that the dropdown base item is a clickable link as well, so this item can receive any of the props of a plain navbar link.

Accepted fields:

Field	Value	Explanation	Required	Default
`label`	`string`	The name to be shown for this item.	Yes
`items`	`LinkLikeItem[]`	The items to be contained in the dropdown.	Yes
`position`	`'left' \| 'right'`	The side of the navbar this item should appear on.	No	`'left'`

Example configuration:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'dropdown',          label: 'Community',          position: 'left',          items: [            {              label: 'Facebook',              href: 'https://www.facebook.com',            },            {              type: 'doc',              label: 'Social',              docId: 'social',            },            // ... more items          ],        },      ],    },  },};

Navbar doc link#

If you want to link to a specific doc, this special navbar item type will render the link to the doc of the provided docId. It will get the class navbar__link--active as long as you browse a doc of the same sidebar.

Accepted fields:

Field	Value	Explanation	Required	Default
`docId`	`string`	The ID of the doc that this item links to.	Yes
`label`	`string`	The name to be shown for this item.	No	`docId`
`position`	`'left' \| 'right'`	The side of the navbar this item should appear on.	No	`'left'`
`activeSidebarClassName`	`string`	The CSS class name to apply when this doc's sidebar is active.	No	`'navbar__link--active'`
`docsPluginId`	`string`	The ID of the docs plugin that the doc belongs to.	No	`'default'`

Example configuration:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'doc',          position: 'left',          docId: 'introduction',          label: 'Docs',        },      ],    },  },};

Navbar docs version dropdown#

If you use docs with versioning, this special navbar item type that will render a dropdown with all your site's available versions.

The user will be able to switch from one version to another, while staying on the same doc (as long as the doc id is constant across versions).

Accepted fields:

Field	Value	Explanation	Required	Default
`position`	`'left' \| 'right'`	The side of the navbar this item should appear on.	No	`'left'`
`dropdownItemsBefore`	`LinkLikeItem[]`	Add additional dropdown items at the beginning of the dropdown.	No	`[]`
`dropdownItemsAfter`	`LinkLikeItem[]`	Add additional dropdown items at the end of the dropdown.	No	`[]`
`docsPluginId`	`string`	The ID of the docs plugin that the doc versioning belongs to.	No	`'default'`
`dropdownActiveClassDisabled`	`boolean`	Do not add the link active class when browsing docs.	No	`false`

Example configuration:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'docsVersionDropdown',          position: 'left',          dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],          dropdownActiveClassDisabled: true,        },      ],    },  },};

Navbar docs version#

If you use docs with versioning, this special navbar item type will link to the active/browsed version of your doc (depends on the current URL), and fallback to the latest version.

Accepted fields:

Field	Value	Explanation	Required	Default
`label`	`string`	The name to be shown for this item.	No	The active/latest version label.
`to`	`string`	The internal link that this item points to.	No	The active/latest version.
`position`	`'left' \| 'right'`	The side of the navbar this item should appear on.	No	`'left'`
`docsPluginId`	`string`	The ID of the docs plugin that the doc versioning belongs to.	No	`'default'`

Example configuration:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'docsVersion',          position: 'left',          to: '/path',          label: 'label',        },      ],    },  },};

Navbar locale dropdown#

If you use the i18n feature, this special navbar item type will render a dropdown with all your site's available locales.

The user will be able to switch from one locale to another, while staying on the same page.

Accepted fields:

Field	Value	Explanation	Required	Default
`position`	`'left' \| 'right'`	The side of the navbar this item should appear on.	No	`'left'`
`dropdownItemsBefore`	`LinkLikeItem[]`	Add additional dropdown items at the beginning of the dropdown.	No	`[]`
`dropdownItemsAfter`	`LinkLikeItem[]`	Add additional dropdown items at the end of the dropdown.	No	`[]`

Example configuration:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'localeDropdown',          position: 'left',          dropdownItemsAfter: [            {              to: 'https://my-site.com/help-us-translate',              label: 'Help us translate',            },          ],        },      ],    },  },};

Navbar search#

If you use the search, the search bar will be the rightmost element in the navbar.

However, with this special navbar item type, you can change the default location.

Field	Value	Explanation	Required	Default
`position`	`'left' \| 'right'`	The side of the navbar this item should appear on.	No	`'left'`

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'search',          position: 'right',        },      ],    },  },};

Auto-hide sticky navbar#

You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    navbar: {      hideOnScroll: true,    },    // ...  },};

Navbar style#

You can set the static Navbar style without disabling the theme switching ability. The selected style will always apply no matter which theme user have selected.

Currently, there are two possible style options: dark and primary (based on the --ifm-color-primary color). You can see the styles preview in the Infima documentation.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    navbar: {      style: 'primary',    },    // ...  },};

CodeBlock#

Docusaurus uses Prism React Renderer to highlight code blocks.

Theme#

By default, we use Palenight as syntax highlighting theme. You can specify a custom theme from the list of available themes. If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    prism: {      theme: require('prism-react-renderer/themes/github'),      darkTheme: require('prism-react-renderer/themes/dracula'),    },    // ...  },};

note

If you use the line highlighting Markdown syntax, you might need to specify a different highlight background color for the dark mode syntax highlighting theme. Refer to the docs for guidance.

Default language#

You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid language name must be passed, e.g.:

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    prism: {      defaultLanguage: 'javascript',    },    // ...  },};

Footer#

You can add logo and a copyright to the footer via themeConfig.footer. Logo can be placed in static folder. Logo URL works in the same way of the navbar logo.

docusaurus.config.js

  // ...  footer: {    logo: {      alt: 'Facebook Open Source Logo',      src: 'img/oss_logo.png',      href: 'https://opensource.facebook.com',    },    copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,  }

Footer Links#

You can add links to the footer via themeConfig.footer.links:

docusaurus.config.js

module.exports = {  // ...  footer: {    links: [      {        // Label of the section of these links        title: 'Docs',        items: [          {            // Label of the link            label: 'Style Guide',            // Client-side routing, used for navigating within the website.            // The baseUrl will be automatically prepended to this value.            to: 'docs/',          },          {            label: 'Second Doc',            to: 'docs/doc2/',          },        ],      },      {        title: 'Community',        items: [          {            label: 'Stack Overflow',            // A full-page navigation, used for navigating outside of the website.            href: 'https://stackoverflow.com/questions/tagged/docusaurus',          },          {            label: 'Discord',            href: 'https://discordapp.com/invite/docusaurus',          },          {            label: 'Twitter',            href: 'https://twitter.com/docusaurus',          },          {            //Renders the html pass-through instead of a simple link            html: `                <a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">                  <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" />                </a>              `,          },        ],      },    ],  },};

Common#

Color mode - dark mode#

caution

Meta image#

Metadatas#

Announcement bar#

i18n#

Translation files location#

Example file-system structure#

Hooks#

useThemeContext#

note

Navbar#

Navbar title & logo#

Navbar items#

Navbar link#

Navbar dropdown#

Navbar doc link#

Navbar docs version dropdown#

Navbar docs version#

Navbar locale dropdown#

Navbar search#

Auto-hide sticky navbar#

Navbar style#

CodeBlock#

Theme#

note

Default language#

Footer#

Footer Links#

`useThemeContext`#