# How to Manage Code Highlighting and Syntax Highlighting in Docusaurus

> Master Docusaurus code highlighting by configuring Prism in docusaurus.config.js. Learn to manage syntax highlighting effectively for your documentation site.

- Repository: [Meta/docusaurus](https://github.com/facebook/docusaurus)
- Tags: how-to-guide
- Published: 2026-03-04

---

**Docusaurus uses Prism via `prism-react-renderer` for syntax highlighting, configured through [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js) and rendered through theme components like [`CodeBlock/Content/index.tsx`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`:

```javascript
// 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](https://github.com/facebook/docusaurus/blob/main/packages/create-docusaurus/templates/classic/docusaurus.config.js#L151-L154))*

## 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`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-common/src/hooks/usePrismTheme.ts), orchestrates this process.

This hook reads the `prism` configuration from [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/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](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-common/src/hooks/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`](https://github.com/facebook/docusaurus/blob/main/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](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-classic/src/theme/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`](https://github.com/facebook/docusaurus/blob/main/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](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-live-codeblock/src/theme/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`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-classic/src/prism-include-languages.ts) as an extension point. Create a file at [`src/theme/prism-include-languages.ts`](https://github.com/facebook/docusaurus/blob/main/src/theme/prism-include-languages.ts) in your site to register custom language definitions:

```typescript
// 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`](https://github.com/facebook/docusaurus/blob/main/src/theme/Root.tsx):

```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](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-classic/src/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/src/css/custom.css):

```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](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-common/src/utils/codeBlockUtils.tsx))*

## Summary

- **Docusaurus uses Prism** via `prism-react-renderer` for all syntax highlighting, configured in [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-common/src/hooks/usePrismTheme.ts), which respects light and dark mode preferences.
- **Code blocks** are rendered by [`CodeBlock/Content/index.tsx`](https://github.com/facebook/docusaurus/blob/main/CodeBlock/Content/index.tsx) (static) and [`Playground/Provider/index.tsx`](https://github.com/facebook/docusaurus/blob/main/Playground/Provider/index.tsx) (live), both consuming the theme from `usePrismTheme`.
- **Language support** extends through [`prism-include-languages.ts`](https://github.com/facebook/docusaurus/blob/main/prism-include-languages.ts), allowing registration of additional Prism language definitions.
- **Styling** leverages CSS variables generated by `getPrismCssVariables` in [`codeBlockUtils.tsx`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js). Both static code blocks ([`CodeBlock/Content/index.tsx`](https://github.com/facebook/docusaurus/blob/main/CodeBlock/Content/index.tsx)) and live playgrounds ([`Playground/Provider/index.tsx`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/src/css/custom.css) targeting the CSS variables exposed by `getPrismCssVariables` in [`packages/docusaurus-theme-common/src/utils/codeBlockUtils.tsx`](https://github.com/facebook/docusaurus/blob/main/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.