This document provides an overview of the Docusaurus theming system, which is responsible for rendering the visual interface of a Docusaurus site. It explains how themes are structured as plugins, how they provide React components for rendering content, and how they integrate with core systems and content plugins.
For detailed information about the classic theme implementation, see Classic Theme. For component customization through swizzling, see Component Swizzling. For styling and CSS architecture, see Styling and UI. For theme system internals and lifecycle, see Theme System Architecture.
The theming system in Docusaurus provides the UI layer that renders documentation content. A theme is a special type of plugin that exports React components accessible via the @theme module alias. These components are used by content plugins (docs, blog, pages) to render their content into web pages. The system supports multiple themes, theme shadowing (swizzling), and shared utilities via theme-common.
Sources: packages/docusaurus-theme-classic/src/theme-classic.d.ts15-21 packages/docusaurus-theme-common/src/index.ts1-14
The following diagram illustrates how themes bridge the gap between raw content data and the final rendered UI, associating high-level systems with specific code entities.
Sources: packages/docusaurus-theme-common/src/index.ts12-60 packages/docusaurus-theme-classic/src/theme-classic.d.ts23-40 packages/docusaurus-theme-common/src/utils/scrollUtils.tsx97-103
The classic theme is the primary UI implementation. It is a plugin that returns a Plugin<undefined> packages/docusaurus-theme-classic/src/index.ts32 and defines the getSwizzleConfig method to control component customization packages/docusaurus-theme-classic/src/index.ts146 It provides the standard layout, including the Navbar, Footer, and DocPage.
Sources: packages/docusaurus-theme-classic/src/theme-classic.d.ts36-40 packages/docusaurus-theme-classic/src/getSwizzleConfig.ts12-13
This package contains the "brain" of the theming system. It provides headless logic, React contexts, and utilities that are theme-agnostic.
ColorModeProvider, AnnouncementBarProvider, and NavbarProvider packages/docusaurus-theme-common/src/internal.ts22-84useThemeConfig, useColorMode, useWindowSize, and useEvent packages/docusaurus-theme-common/src/index.ts13-60ThemeClassNames, a registry of stable CSS class names (e.g., theme-doc-markdown) intended for user styling packages/docusaurus-theme-common/src/index.ts40Docusaurus uses a Webpack/Rspack alias @theme to resolve components. This allows for "Theme Shadowing," where a file in the user's src/theme directory overrides the default theme component packages/docusaurus-theme-classic/src/theme-classic.d.ts15-21
The theme-classic package declares a vast array of components organized into functional groups:
AnnouncementBar, BackToTopButton, ColorModeToggle packages/docusaurus-theme-classic/src/theme-classic.d.ts172-198Admonition, CodeBlock, Tabs, Details packages/docusaurus-theme-classic/src/theme-classic.d.ts42-162Navbar, Footer, DocSidebar packages/docusaurus-theme-classic/src/theme-classic.d.ts468-593Themes provide an MDXComponents mapping that replaces standard HTML elements with themed React components (e.g., replacing <a> with a themed Link or <img> with a ThemedImage).
Sources: packages/docusaurus-theme-classic/src/theme-classic.d.ts1107-1148
Themes also integrate with search providers like Algolia. The @docusaurus/theme-search-algolia package provides components like SearchBar and SearchPage that interact with the Algolia API using contextual filters.
Sources: packages/docusaurus-theme-search-algolia/src/theme/SearchBar/index.tsx23-28 packages/docusaurus-theme-search-algolia/src/theme/SearchPage/index.tsx20-38
Themes export a SwizzleConfig which dictates which components are "safe" or "unsafe" to swizzle (eject or wrap).
| Component | Eject Action | Wrap Action | Description |
|---|---|---|---|
Footer | safe | safe | The site's layout footer packages/docusaurus-theme-classic/src/getSwizzleConfig.ts209-215 |
CodeBlock | safe | safe | Renders multi-line code blocks packages/docusaurus-theme-classic/src/getSwizzleConfig.ts151-158 |
DocSidebar | unsafe | safe | The sidebar on docs pages packages/docusaurus-theme-classic/src/getSwizzleConfig.ts202-208 |
Admonition/Icon | safe | forbidden | Folder containing icons packages/docusaurus-theme-classic/src/getSwizzleConfig.ts15-21 |
Sources: packages/docusaurus-theme-classic/src/getSwizzleConfig.ts15-240
Content plugins (Docs, Blog) are decoupled from the UI but rely on specific theme components to exist. For example, the Docs plugin expects @theme/DocItem to be available to render a document page.
DocCard, DocPaginator, and DocVersionBanner packages/docusaurus-theme-classic/src/theme-classic.d.ts280-380BlogPostItem, BlogListPaginator, and BlogSidebar packages/docusaurus-theme-classic/src/theme-classic.d.ts595-643Sources: packages/docusaurus-theme-classic/src/theme-classic.d.ts10-13
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.