website/docs/api/themes/theme-configuration.mdx - main - githubmirror/docusaurus

website/docs/api/themes/theme-configuration.mdx
1 239 строк36 KB
Francisco Marín
docs: fix versionPersistence default value in theme config table (#12258)
10 июл 2026, 13:30
10 июл 2026, 13:3090ea711
---
sidebar_position: 1
sidebar_label: Configuration
slug: /api/themes/configuration
toc_max_heading_level: 4
---

# Theme configuration

import APITable from '@site/src/components/APITable';

This configuration applies to all [main themes](./overview.mdx).

## Common {/* #common */}

### Color mode {/* #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 within the `colorMode` object.

Accepted fields:

```mdx-code-block
<APITable>
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultMode` | <code>'light' \| 'dark'</code> | `'light'` | The color mode when user first visits the site. |
| `disableSwitch` | `boolean` | `false` | Hides the switch in the navbar. Useful if you want to support a single color mode. |
| `respectPrefersColorScheme` | `boolean` | `false` | Whether to use the `prefers-color-scheme` media-query, using user system preferences, instead of the hardcoded `defaultMode`. |

```mdx-code-block
</APITable>
```

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    // highlight-start
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: false,
    },
    // highlight-end
  },
};
```

:::warning

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 {/* #meta-image */}

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

Accepted fields:

```mdx-code-block
<APITable>
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `image` | `string` | `undefined` | The meta image URL for the site. Relative to your site's "static" directory. Cannot be SVGs. Can be external URLs too. |

```mdx-code-block
</APITable>
```

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    // highlight-next-line
    image: 'img/docusaurus.png',
  },
};
```

### Metadata {/* #metadata */}

You can configure additional HTML metadata (and override existing ones).

Accepted fields:

```mdx-code-block
<APITable>
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `metadata` | `Metadata[]` | `[]` | Any field will be directly passed to the `<meta />` tag. Possible fields include `id`, `name`, `property`, `content`, `itemprop`, etc. |

```mdx-code-block
</APITable>
```

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    // highlight-next-line
    metadata: [{name: 'twitter:card', content: 'summary'}],
  },
};
```

### Announcement bar {/* #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 dismissible panel above the navbar. All configuration are in the `announcementBar` object.

Accepted fields:

```mdx-code-block
<APITable name="announcement-bar">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | `'announcement-bar'` | Any value that will identify this message. |
| `content` | `string` | `''` | The text content of the announcement. HTML will be interpolated. |
| `backgroundColor` | `string` | `'#fff'` | Background color of the entire bar. |
| `textColor` | `string` | `'#000'` | Announcement text color. |
| `isCloseable` | `boolean` | `true` | Whether this announcement can be dismissed with a '×' button. |

```mdx-code-block
</APITable>
```

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    // highlight-start
    announcementBar: {
      id: 'support_us',
      content:
        'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>',
      backgroundColor: '#fafbfc',
      textColor: '#091E42',
      isCloseable: false,
    },
    // highlight-end
  },
};
```

## Plugins {/* #plugins */}

Our [main themes](./overview.mdx) offer additional theme configuration options for Docusaurus core content plugins.

### Docs {/* #docs */}

```mdx-code-block
<APITable name="navbar-overview">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `versionPersistence` | `'localStorage' \| 'none'` | `'localStorage'` | Defines the browser persistence of the preferred docs version. |
| `sidebar.hideable` | `boolean` | `false` | Show a hide button at the bottom of the sidebar. |
| `sidebar.autoCollapseCategories` | `boolean` | `false` | Automatically collapse all sibling categories of the one you navigate to. |

```mdx-code-block
</APITable>
```

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    docs: {
      // highlight-start
      versionPersistence: 'localStorage',
      sidebar: {
        hideable: false,
        autoCollapseCategories: false,
      },
      // highlight-end
    },
  },
};
```

### Blog {/* #blog */}

```mdx-code-block
<APITable name="navbar-overview">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `sidebar.groupByYear` | `boolean` | `true` | Group sidebar blog posts by years. |

```mdx-code-block
</APITable>
```

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    blog: {
      // highlight-start
      sidebar: {
        groupByYear: true,
      },
      // highlight-end
    },
  },
};
```

## Navbar {/* #navbar */}

Accepted fields:

```mdx-code-block
<APITable name="navbar-overview">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `undefined` | Title for the navbar. |
| `logo` | _See below_ | `undefined` | Customization of the logo object. |
| `items` | `NavbarItem[]` | `[]` | A list of navbar items. See specification below. |
| `hideOnScroll` | `boolean` | `false` | Whether the navbar is hidden when the user scrolls down. |
| `style` | <code>'primary' \| 'dark'</code> | Same as theme | Sets the navbar style, ignoring the dark/light theme. |

```mdx-code-block
</APITable>
```

### Navbar logo {/* #navbar-logo */}

The logo can be placed in [static folder](static-assets.mdx). 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.

Accepted fields:

```mdx-code-block
<APITable name="navbar-logo">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `alt` | `string` | `undefined` | Alt tag for the logo image. |
| `src` | `string` | **Required** | URL to the logo image. Base URL is appended by default. |
| `srcDark` | `string` | `logo.src` | An alternative image URL to use in dark mode. |
| `href` | `string` | `siteConfig.baseUrl` | Link to navigate to when the logo is clicked. |
| `width` | <code>string \| number</code> | `undefined` | Specifies the `width` attribute. |
| `height` | <code>string \| number</code> | `undefined` | Specifies the `height` attribute. |
| `target` | `string` | Calculated based on `href` (external links will open in a new tab, all others in the current one). | The `target` attribute of the link; controls whether the link is opened in a new tab, the current one, or otherwise. |
| `className` | `string` | `undefined` | CSS class applied to the image. |
| `style` | `object` | `undefined` | CSS inline style object. React/JSX flavor, using camelCase properties. |

```mdx-code-block
</APITable>
```

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      title: 'Site Title',
      // highlight-start
      logo: {
        alt: 'Site Logo',
        src: 'img/logo.svg',
        srcDark: 'img/logo_dark.svg',
        href: 'https://docusaurus.io/',
        target: '_self',
        width: 32,
        height: 32,
        className: 'custom-navbar-logo-class',
        style: {border: 'solid red'},
      },
      // highlight-end
    },
  },
};
```

### Navbar items {/* #navbar-items */}

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

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      // highlight-start
      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',
        },
      ],
      // highlight-end
    },
  },
};
```

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 {/* #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:

```mdx-code-block
<APITable name="navbar-link">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'default'` | Optional | Sets the type of this item to a link. |
| `label` | `string` | **Required** | The name to be shown for this item. |
| `html` | `string` | Optional | Same as `label`, but renders pure HTML instead of text content. |
| `to` | `string` | **Required** | Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value. |
| `href` | `string` | **Required** | A full-page navigation, used for navigating outside of the website. **Only one of `to` or `href` should be used.** |
| `prependBaseUrlToHref` | `boolean` | `false` | Prepends the baseUrl to `href` values. |
| `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
| `activeBasePath` | `string` | `to` / `href` | To apply the active class styling on all routes starting with this path. This usually isn't necessary. |
| `activeBaseRegex` | `string` | `undefined` | Alternative to `activeBasePath` if required. |
| `className` | `string` | `''` | Custom CSS class (for styling any item). |

```mdx-code-block
</APITable>
```

:::note

In addition to the fields above, you can specify other arbitrary attributes that can be applied to a HTML link.

:::

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      items: [
        // highlight-start
        {
          to: 'docs/introduction',
          // Only one of "to" or "href" should be used
          // href: 'https://www.facebook.com',
          label: 'Introduction',
          // Only one of "label" or "html" should be used
          // html: '<b>Introduction</b>'
          position: 'left',
          activeBaseRegex: 'docs/(next|v8)',
          target: '_blank',
        },
        // highlight-end
      ],
    },
  },
};
```

#### Navbar dropdown {/* #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-link)
- [Navbar doc link](#navbar-doc-link)
- [Navbar docs version](#navbar-docs-version)
- [Navbar doc sidebar](#navbar-doc-sidebar)
- [Navbar with custom HTML](#navbar-with-custom-html)

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](#navbar-link).

Accepted fields:

```mdx-code-block
<APITable name="navbar-dropdown">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'dropdown'` | Optional | Sets the type of this item to a dropdown. |
| `label` | `string` | **Required** | The name to be shown for this item. |
| `items` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | **Required** | The items to be contained in the dropdown. |
| `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |

```mdx-code-block
</APITable>
```

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      items: [
        // highlight-start
        {
          type: 'dropdown',
          label: 'Community',
          position: 'left',
          items: [
            {
              label: 'Facebook',
              href: 'https://www.facebook.com',
            },
            {
              type: 'doc',
              label: 'Social',
              docId: 'social',
            },
            // ... more items
          ],
        },
        // highlight-end
      ],
    },
  },
};
```

#### Navbar doc link {/* #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:

```mdx-code-block
<APITable name="navbar-doc-link">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'doc'` | **Required** | Sets the type of this item to a doc link. |
| `docId` | `string` | **Required** | The ID of the doc that this item links to. |
| `label` | `string` | `docId` | The name to be shown for this item. |
| `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
| `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc belongs to. |

```mdx-code-block
</APITable>
```

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      items: [
        // highlight-start
        {
          type: 'doc',
          position: 'left',
          docId: 'introduction',
          label: 'Docs',
        },
        // highlight-end
      ],
    },
  },
};
```

#### Navbar linked to a sidebar {/* #navbar-doc-sidebar */}

You can link a navbar item to the first document link (which can be a doc link or a generated category index) of a given sidebar without having to hardcode a doc ID.

Accepted fields:

```mdx-code-block
<APITable name="navbar-doc-sidebar">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'docSidebar'` | **Required** | Sets the type of this navbar item to a sidebar's first document. |
| `sidebarId` | `string` | **Required** | The ID of the sidebar that this item is linked to. |
| `label` | `string` | First document link's sidebar label | The name to be shown for this item. |
| `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
| `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the sidebar belongs to. |

```mdx-code-block
</APITable>
```

:::tip

Use this navbar item type if your sidebar is updated often and the order is not stable.

:::

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      items: [
        // highlight-start
        {
          type: 'docSidebar',
          position: 'left',
          sidebarId: 'api',
          label: 'API',
        },
        // highlight-end
      ],
    },
  },
};
```

```js title="sidebars.js"
export default {
  tutorial: [
    {
      type: 'autogenerated',
      dirName: 'guides',
    },
  ],
  api: [
    // highlight-next-line
    'cli', // The navbar item will be linking to this doc
    'docusaurus-core',
    {
      type: 'autogenerated',
      dirName: 'api',
    },
  ],
};
```

#### Navbar docs version dropdown {/* #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:

```mdx-code-block
<APITable name="navbar-docs-version-dropdown">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'docsVersionDropdown'` | **Required** | Sets the type of this item to a docs version dropdown. |
| `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
| `dropdownItemsBefore` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the beginning of the dropdown. |
| `dropdownItemsAfter` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the end of the dropdown. |
| `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. |
| `dropdownActiveClassDisabled` | `boolean` | `false` | Do not add the link active class when browsing docs. |
| `versions` | `DropdownVersions` | `undefined` | Specify a custom list of versions to include in the dropdown. See [the versioning guide](../../guides/docs/versioning.mdx#docsVersionDropdown) for details. |

```mdx-code-block
</APITable>
```

Types:

```ts
type DropdownVersion = {
  /** Allows you to provide a custom display label for each version. */
  label?: string;
};

type DropdownVersions = string[] | {[versionName: string]: DropdownVersion};
```

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      items: [
        // highlight-start
        {
          type: 'docsVersionDropdown',
          position: 'left',
          dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],
          dropdownActiveClassDisabled: true,
        },
        // highlight-end
      ],
    },
  },
};
```

#### Navbar docs version {/* #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:

```mdx-code-block
<APITable name="navbar-docs-version">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'docsVersion'` | **Required** | Sets the type of this item to a doc version link. |
| `label` | `string` | The active/latest version label. | The name to be shown for this item. |
| `to` | `string` | The active/latest version. | The internal link that this item points to. |
| `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
| `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. |

```mdx-code-block
</APITable>
```

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      items: [
        // highlight-start
        {
          type: 'docsVersion',
          position: 'left',
          to: '/path',
          label: 'label',
        },
        // highlight-end
      ],
    },
  },
};
```

#### Navbar locale dropdown {/* #navbar-locale-dropdown */}

If you use the [i18n feature](../../i18n/i18n-introduction.mdx), 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:

```mdx-code-block
<APITable name="navbar-locale-dropdown">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'localeDropdown'` | **Required** | Sets the type of this item to a locale dropdown. |
| `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
| `dropdownItemsBefore` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the beginning of the dropdown. |
| `dropdownItemsAfter` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the end of the dropdown. |
| `queryString` | `string` | `undefined` | The query string to be appended to the URL. |

```mdx-code-block
</APITable>
```

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      items: [
        // highlight-start
        {
          type: 'localeDropdown',
          position: 'left',
          dropdownItemsAfter: [
            {
              to: 'https://my-site.com/help-us-translate',
              label: 'Help us translate',
            },
          ],
        },
        // highlight-end
      ],
    },
  },
};
```

#### Navbar search {/* #navbar-search */}

If you use the [search](../../search.mdx), the search bar will be the rightmost element in the navbar.

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

```mdx-code-block
<APITable name="navbar-search">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'search'` | **Required** | Sets the type of this item to a search bar. |
| `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
| `className` | `string` | / | Custom CSS class for this navbar item. |

```mdx-code-block
</APITable>
```

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      items: [
        // highlight-start
        {
          type: 'search',
          position: 'right',
        },
        // highlight-end
      ],
    },
  },
};
```

#### Navbar with custom HTML {/* #navbar-with-custom-html */}

You can also render your own HTML markup inside a navbar item using this navbar item type.

```mdx-code-block
<APITable name="navbar-html">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'html'` | **Required** | Sets the type of this item to a HTML element. |
| `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
| `className` | `string` | `''` | Custom CSS class for this navbar item. |
| `value` | `string` | `''` | Custom HTML to be rendered inside this navbar item. |

```mdx-code-block
</APITable>
```

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      items: [
        // highlight-start
        {
          type: 'html',
          position: 'right',
          value: '<button>Give feedback</button>',
        },
        // highlight-end
      ],
    },
  },
};
```

### Auto-hide sticky navbar {/* #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.

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      // highlight-next-line
      hideOnScroll: true,
    },
  },
};
```

### Navbar style {/* #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](https://infima.dev/docs/components/navbar/).

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      // highlight-next-line
      style: 'primary',
    },
  },
};
```

## CodeBlock {/* #codeblock */}

Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight code blocks. All configuration are in the `prism` object.

Accepted fields:

```mdx-code-block
<APITable name="codeblock">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `PrismTheme` | `palenight` | The Prism theme to use for light-theme code blocks. |
| `darkTheme` | `PrismTheme` | `palenight` | The Prism theme to use for dark-theme code blocks. |
| `defaultLanguage` | `string` | `undefined` | The default language to use for code blocks not declaring any explicit language. |
| `magicComments` | `MagicCommentConfig[]` | _see below_ | The list of [magic comments](../../guides/markdown-features/markdown-features-code-blocks.mdx#custom-magic-comments). |

```mdx-code-block
</APITable>
```

```ts
type MagicCommentConfig = {
  className: string;
  line?: string;
  block?: {start: string; end: string};
};
```

```js
const defaultMagicComments = [
  {
    className: 'theme-code-block-highlighted-line',
    line: 'highlight-next-line',
    block: {start: 'highlight-start', end: 'highlight-end'},
  },
];
```

### Theme {/* #theme */}

By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/packages/prism-react-renderer/src/themes/palenight.ts) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/packages/prism-react-renderer/src/themes). You may also use a different syntax highlighting theme when the site is in dark mode.

Example configuration:

```js title="docusaurus.config.js"
import {themes as prismThemes} from 'prism-react-renderer';

export default {
  themeConfig: {
    prism: {
      // highlight-start
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
      // highlight-end
    },
  },
};
```

:::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](../../guides/markdown-features/markdown-features-code-blocks.mdx#line-highlighting).

:::

### Default language {/* #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](https://prismjs.com/#supported-languages) must be passed.

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    prism: {
      // highlight-next-line
      defaultLanguage: 'javascript',
    },
  },
};
```

## Footer {/* #footer-1 */}

You can add logo and a copyright to the footer via `themeConfig.footer`. Logo can be placed in [static folder](static-assets.mdx). Logo URL works in the same way of the navbar logo.

Accepted fields:

```mdx-code-block
<APITable name="footer">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `logo` | `Logo` | `undefined` | Customization of the logo object. See [Navbar logo](#navbar-logo) for details. |
| `copyright` | `string` | `undefined` | The copyright message to be displayed at the bottom, also supports custom HTML. |
| `style` | <code>'dark' \| 'light'</code> | `'light'` | The color theme of the footer component. |
| `links` | <code>(Column \| FooterLink)[]</code> | `[]` | The link groups to be present. |

```mdx-code-block
</APITable>
```

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    // highlight-start
    footer: {
      logo: {
        alt: 'Meta Open Source Logo',
        src: 'img/meta_oss_logo.png',
        href: 'https://opensource.fb.com',
        width: 160,
        height: 51,
      },
      copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
    },
    // highlight-end
  },
};
```

### Footer Links {/* #footer-links */}

You can add links to the footer via `themeConfig.footer.links`. There are two types of footer configurations: **multi-column footers** and **simple footers**.

Multi-column footer links have a `title` and a list of `FooterItem`s for each column.

```mdx-code-block
<APITable name="footer-links">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `undefined` | Label of the section of these links. |
| `items` | `FooterItem[]` | `[]` | Links in this section. |

```mdx-code-block
</APITable>
```

Accepted fields of each `FooterItem`:

```mdx-code-block
<APITable name="footer-items">
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | **Required** | Text to be displayed for this link. |
| `to` | `string` | **Required** | Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value. |
| `href` | `string` | **Required** | A full-page navigation, used for navigating outside of the website. **Only one of `to` or `href` should be used.** |
| `html` | `string` | `undefined` | Renders the HTML pass-through instead of a simple link. In case `html` is used, no other options should be provided. |

```mdx-code-block
</APITable>
```

Example multi-column configuration:

```js title="docusaurus.config.js"
export default {
  footer: {
    // highlight-start
    links: [
      {
        title: 'Docs',
        items: [
          {
            label: 'Style Guide',
            to: 'docs/',
          },
          {
            label: 'Second Doc',
            to: 'docs/doc2/',
          },
        ],
      },
      {
        title: 'Community',
        items: [
          {
            label: 'Stack Overflow',
            href: 'https://stackoverflow.com/questions/tagged/docusaurus',
          },
          {
            label: 'Discord',
            href: 'https://discordapp.com/invite/docusaurus',
          },
          {
            label: 'X',
            href: 'https://x.com/docusaurus',
          },
          {
            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" width="114" height="51" />
                </a>
              `,
          },
        ],
      },
    ],
    // highlight-end
  },
};
```

A simple footer just has a list of `FooterItem`s displayed in a row.

Example simple configuration:

```js title="docusaurus.config.js"
export default {
  footer: {
    // highlight-start
    links: [
      {
        label: 'Stack Overflow',
        href: 'https://stackoverflow.com/questions/tagged/docusaurus',
      },
      {
        label: 'Discord',
        href: 'https://discordapp.com/invite/docusaurus',
      },
      {
        label: 'X',
        href: 'https://x.com/docusaurus',
      },
      {
        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" width="114" height="51" />
            </a>
          `,
      },
    ],
    // highlight-end
  },
};
```

## Table of Contents {/* #table-of-contents */}

You can adjust the default table of contents via `themeConfig.tableOfContents`.

```mdx-code-block
<APITable>
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `minHeadingLevel` | `number` | `2` | The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value. |
| `maxHeadingLevel` | `number` | `3` | Max heading level displayed in the TOC. Should be an integer between 2 and 6. |

```mdx-code-block
</APITable>
```

Example configuration:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    // highlight-start
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
    // highlight-end
  },
};
```

## Hooks {/* #hooks */}

### `useColorMode` {/* #use-color-mode */}

A React hook to access the color context. This context contains functions for selecting light/dark/system mode and exposes the current color mode and the choice from the user. The color mode values **should not be used for dynamic content rendering** (see below).

Usage example:

```jsx
// highlight-next-line
import {useColorMode} from '@docusaurus/theme-common';

const MyColorModeButton = () => {
  // highlight-start
  const {
    colorMode, // the "effective" color mode, never null
    colorModeChoice, // the color mode chosen by the user, can be null
    setColorMode, // set the color mode chosen by the user
  } = useColorMode();
  // highlight-end

  return (
    <button
      onClick={() => {
        const nextColorMode = colorModeChoice === 'dark' ? 'light' : 'dark';
        setColorMode(nextColorMode);
      }}>
      Toggle color mode
    </button>
  );
};
```

Attributes:

- `colorMode: 'light' | 'dark'`: The effective color mode currently applied to the UI. It cannot be `null`.
- `colorModeChoice: 'light' | 'dark' | null`: The color mode explicitly chosen by the user. It can be `null` if user has not made any choice yet, or if they reset their choice to the system/default value.
- `setColorMode(colorModeChoice: 'light' | 'dark' | null, options: {persist: boolean}): void`: A function to call when the user explicitly chose a color mode. `null` permits to reset the choice to the system/default value. By default, the choice is persisted in `localStorage` and restored on page reload, but you can opt out with `{persist: false}`.

:::warning

Don't use `colorMode` and `colorModeChoice` while rendering React components. Doing so is likely to produce [FOUC](https://en.wikipedia.org/wiki/Flash_of_unstyled_content), layout shifts and [React hydration](https://18.react.dev/reference/react-dom/client/hydrateRoot) mismatches if you use them to render JSX content dynamically.

However, these values are safe to use **after React hydration**, in `useEffect` and event listeners, like in the `MyColorModeButton` example above.

If you need to render content dynamically depending on the current theme, the only way to avoid FOUC, layout shifts and hydration mismatch is to rely on CSS selectors to render content dynamically, based on the `html` data attributes that we set before the page displays anything:

```html
<html data-theme="<light | dark>" data-theme-choice="<light | dark | system>">
  <!-- content -->
</html>
```

```css
[data-theme='light']
[data-theme='dark']

[data-theme-choice='light']
[data-theme-choice='dark']
[data-theme-choice='system']
```

<details>
 <summary>Why are `colorMode` and `colorModeChoice` unsafe when rendering?</summary>

To understand the problem, you need to understand how [React hydration](https://18.react.dev/reference/react-dom/client/hydrateRoot) works.

During the static site generation phase, Docusaurus doesn't know what the user color mode choice is, and `useColorMode()` returns the following static values:

- `colorMode = themeConfig.colorMode.defaultMode`
- `colorModeChoice = null`

During the very first React client-side render (the hydration), React must produce the exact same HTML markup, and will also use these static values.

The correct `colorMode` and `colorModeChoice` values will only be provided in the second React render.

Typically, the following component will lead to **React hydration mismatches**. The label may switch from `light` to `dark` while React hydrates, leading to a confusing user experience.

```jsx
import {useColorMode} from '@docusaurus/theme-common';

const DisplayCurrentColorMode = () => {
  const {colorMode} = useColorMode();
  return <span>{colorMode}</span>;
};
```

</details>

:::

:::note

The component calling `useColorMode` must be a child of the `Layout` component.

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

:::

## i18n {/* #i18n */}

Read the [i18n introduction](../../i18n/i18n-introduction.mdx) first.

### Translation files location {/* #translation-files-location */}

- **Base path**: `website/i18n/[locale]/docusaurus-theme-[themeName]`
- **Multi-instance path**: N/A
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.mdx#docusaurus-write-translations-sitedir)
- **Markdown files**: N/A

### Example file-system structure {/* #example-file-system-structure */}

```bash
website/i18n/[locale]/docusaurus-theme-classic
│
│ # translations for the theme
├── navbar.json
└── footer.json
```