How to Manage Code Highlighting and Syntax Highlighting in Docusaurus

Docusaurus uses Prism via prism-react-renderer for syntax highlighting, configured through docusaurus.config.js and rendered through theme components like CodeBlock/Content/index.tsx.

The facebook/docusaurus repository provides a complete syntax highlighting pipeline that supports both static code blocks and live playgrounds. Understanding how to configure and extend this system allows you to control code highlighting and syntax highlighting in Docusaurus across light and dark modes.

Configuring Prism Themes in docusaurus.config.js

Docusaurus delegates all syntax highlighting to Prism through the prism-react-renderer package. You declare your preferred themes in the prism object inside docusaurus.config.js.

The configuration requires a theme for light mode and optionally a darkTheme for dark mode. These values are plain JavaScript objects exported by prism-react-renderer:

// docusaurus.config.js
import {themes as prismThemes} from 'prism-react-renderer';

export default {
  themeConfig: {
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  },
};

(source: docusaurus.config.js example)

How Docusaurus Selects Themes at Runtime

Theme selection happens dynamically based on the user's color mode preference. The usePrismTheme hook, located in packages/docusaurus-theme-common/src/hooks/usePrismTheme.ts, orchestrates this process.

This hook reads the prism configuration from docusaurus.config.js and the current color mode (light or dark). It returns the appropriate theme object for the active mode, ensuring code highlighting and syntax highlighting in Docusaurus remain consistent with the site theme.

(source: usePrismTheme.ts)

Rendering Code Blocks with Syntax Highlighting

Docusaurus renders highlighted code through specialized theme components that consume the Prism theme provided by usePrismTheme.

Static Code Blocks

The classic theme's code block component at packages/docusaurus-theme-classic/src/theme/CodeBlock/Content/index.tsx imports usePrismTheme and passes the returned theme to the Highlight component from prism-react-renderer. This transforms raw code strings into syntax-highlighted HTML with proper tokenization.

(source: CodeBlock/Content/index.tsx)

Live Code Playgrounds

For interactive examples, the live code block theme uses packages/docusaurus-theme-live-codeblock/src/theme/Playground/Provider/index.tsx. This provider also leverages usePrismTheme to ensure the Monaco-style editor reflects the correct syntax highlighting theme while maintaining consistency with static code blocks.

(source: Playground/Provider/index.tsx)

Adding Support for Additional Languages

By default, Prism includes only a core set of languages. You can extend support for additional syntaxes using the prism-include-languages utility.

The classic theme provides packages/docusaurus-theme-classic/src/prism-include-languages.ts as an extension point. Create a file at src/theme/prism-include-languages.ts in your site to register custom language definitions:

// src/theme/prism-include-languages.ts
import {Prism} from 'prism-react-renderer';
import toml from 'prismjs/components/prism-toml';

export default function prismIncludeLanguages(PrismInstance: typeof Prism) {
  PrismInstance.languages.toml = toml;
}

Then import and invoke this function in a top-level component such as src/theme/Root.tsx:

// src/theme/Root.tsx
import prismIncludeLanguages from '@theme/prism-include-languages';
import {Prism} from 'prism-react-renderer';

prismIncludeLanguages(Prism);

(source: prism-include-languages.ts)

Customizing Code Highlighting Styles

Docusaurus exposes Prism theme values as CSS variables through the getPrismCssVariables utility in packages/docusaurus-theme-common/src/utils/codeBlockUtils.tsx. This function extracts color values from the selected theme and injects them as inline CSS variables, enabling custom styling through your own CSS.

Override default styles by targeting these variables in src/css/custom.css:

/* src/css/custom.css */
[data-theme='dark'] .prism-code {
  background-color: var(--prism-background-color);
  color: var(--prism-color);
}

/* Increase line height for readability */
.prism-code {
  line-height: 1.6;
}

(source: codeBlockUtils.tsx)

Summary

• Docusaurus uses Prism via prism-react-renderer for all syntax highlighting, configured in docusaurus.config.js through the prism object.
• Theme selection is handled dynamically by the usePrismTheme hook in packages/docusaurus-theme-common/src/hooks/usePrismTheme.ts, which respects light and dark mode preferences.
• Code blocks are rendered by CodeBlock/Content/index.tsx (static) and Playground/Provider/index.tsx (live), both consuming the theme from usePrismTheme.
• Language support extends through prism-include-languages.ts, allowing registration of additional Prism language definitions.
• Styling leverages CSS variables generated by getPrismCssVariables in codeBlockUtils.tsx, enabling custom overrides without breaking theme consistency.

Frequently Asked Questions

How do I change the syntax highlighting theme in Docusaurus?

Import your desired theme from prism-react-renderer and assign it to the theme (light mode) and darkTheme (dark mode) properties in the prism configuration object within docusaurus.config.js. The usePrismTheme hook automatically selects the appropriate theme based on the user's color mode preference.

Can I add support for custom programming languages in Docusaurus code blocks?

Yes. Create a src/theme/prism-include-languages.ts file that imports the Prism object from prism-react-renderer and registers your custom language grammar. Import and execute this function in src/theme/Root.tsx to ensure the language definitions load before your site renders.

How does Docusaurus handle syntax highlighting in dark mode?

The usePrismTheme hook in packages/docusaurus-theme-common/src/hooks/usePrismTheme.ts detects the current color mode and returns either the theme or darkTheme object specified in docusaurus.config.js. Both static code blocks (CodeBlock/Content/index.tsx) and live playgrounds (Playground/Provider/index.tsx) consume this hook to ensure consistent highlighting across modes.

Where can I override the default code block styles in Docusaurus?

Add custom CSS to src/css/custom.css targeting the CSS variables exposed by getPrismCssVariables in packages/docusaurus-theme-common/src/utils/codeBlockUtils.tsx. You can override --prism-background-color, --prism-color, and other token-specific variables to customize appearance without modifying the underlying Prism theme objects.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}