Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/facebook/docusaurus/llms.txt

Use this file to discover all available pages before exploring further.

Docusaurus themes control the visual presentation and user interface of your documentation site. Unlike plugins, which add data-processing capabilities and content sources, themes contribute React components and global CSS that determine what visitors actually see and interact with. Every Docusaurus site needs at least one main theme to render its pages; enhancement themes layer on top to add features such as search and interactive code playgrounds.

​
Themes vs. plugins

The distinction between themes and plugins in Docusaurus is subtle but important. Both are packages that hook into the Docusaurus lifecycle, but they serve different roles:
AspectPluginsThemes
Primary purposeLoad and transform contentProvide UI components and styles
Contributes routesYes (via addRoute)Rarely
Contributes componentsNoYes (via theme path)
Exampleplugin-content-docstheme-classic
A theme package exposes a theme path — a directory of React components that Docusaurus resolves when it renders pages. When a plugin produces a page (for example, a doc page), it declares which theme component should render that page, and the active theme supplies that component.

​
The component override (swizzling) system

Docusaurus allows you to replace or wrap any theme component with your own version — a process called swizzling. This gives you fine-grained control over every element of the UI without forking the entire theme.
Ejecting copies the original component source into your site’s src/theme/ directory, where you can modify it freely.
npx docusaurus swizzle @docusaurus/theme-classic Navbar --eject
Some components are marked unsafe for swizzling because their internal API is subject to change between releases. Ejecting an unsafe component means you take on the responsibility of keeping it up to date with upstream changes.
Prefer wrapping over ejecting whenever possible. Wrapped components continue to receive upstream bug fixes and feature improvements automatically.
After swizzling, your local src/theme/ComponentName/index.js takes precedence over the package’s version. Docusaurus resolves theme components using an alias chain: your site overrides → theme package → fallback defaults.

​
Official themes

Docusaurus ships several official themes, split into main themes (which provide a complete UI) and enhancement themes (which augment an existing main theme).

​
Main themes

@docusaurus/theme-classic

The production-ready default theme used by most Docusaurus sites. Provides a full UI including navbar, footer, sidebar, table of contents, doc layout, blog layout, search bar slot, and all standard page types. Built on the Infima CSS framework and fully customizable via CSS variables. Included automatically when you use @docusaurus/preset-classic.
Additional main themes are planned for the future. The goal is for all main themes to share the same features, configuration API, and user experience, differing only in visual design and styling framework. As of now, only theme-classic is production-ready.

​
Enhancement themes

Enhancement themes add specific capabilities on top of any main theme. They do not provide a complete UI on their own.

@docusaurus/theme-live-codeblock

Powers interactive, editable code blocks in your MDX content using react-live. Add live to any code fence to make it executable in the browser. Configure the playground position via themeConfig.liveCodeBlock.playgroundPosition.

@docusaurus/theme-search-algolia

Integrates Algolia DocSearch into your site’s navbar. Provides a SearchBar component and a dedicated search results page at /search. Requires Algolia credentials configured in themeConfig.algolia.

@docusaurus/theme-mermaid

Renders Mermaid diagrams defined in fenced code blocks with the mermaid language tag. Requires enabling the Remark plugin via markdown.mermaid: true in docusaurus.config.js.

​
Installation and usage

Most Docusaurus users install themes through the @docusaurus/preset-classic preset, which bundles theme-classic and theme-search-algolia together. If you need an enhancement theme separately, install it as a package and register it under the themes key in your config.
docusaurus.config.js
export default {
  themes: [
    '@docusaurus/theme-live-codeblock',
    '@docusaurus/theme-mermaid',
  ],
  // preset-classic already includes theme-classic and theme-search-algolia
  presets: [
    [
      'classic',
      {
        theme: {
          customCss: './src/css/custom.css',
        },
      },
    ],
  ],
};

​
Theme configuration

All theme visual options — color mode, navbar, footer, code highlighting, and table of contents — are set inside the themeConfig object in docusaurus.config.js. See the Theme Configuration reference for a complete field listing.

Build docs developers (and LLMs) love

Get started for freeTalk to us