Syntax Highlighting

Expressive Code’s default syntax highlighter is Shiki, which uses the same engine as VS Code to provide accurate syntax highlighting for over 100 languages.

No installation required

These features are provided by @expressive-code/plugin-shiki, which is installed & enabled by default in all framework integrations. You can start using it right away in your documents!

Usage in markdown / MDX

Regular syntax highlighting

To get syntax highlighting for your code blocks, wrap them in code fences (using three or more backticks) and ensure that your opening code fences include a language identifier, e.g. js for JavaScript:

example.md

```js
console.log('This code is syntax highlighted!')
```

The rendered result looks like this:

console.log('This code is syntax highlighted!')

Rendering ANSI escape sequences

Expressive Code supports rendering a subset of ANSI escape sequences. This can be useful for displaying formatted terminal output in your documentation.

To enable this feature for a code block, set its language identifier in the opening code fence to ansi. You can then use the following ANSI escape sequences:

ansi-example.md

```ansi
ANSI colors:
- Regular: Red Green Yellow Blue Magenta Cyan
- Bold:    Red Green Yellow Blue Magenta Cyan
- Dimmed:  Red Green Yellow Blue Magenta Cyan

256 colors (showing colors 160-177):
160 161 162 163 164 165
166 167 168 169 170 171
172 173 174 175 176 177

Full RGB colors:
ForestGreen - RGB(34, 139, 34)

Text formatting: Bold Dimmed Italic Underline
```

Result:

ANSI colors:
- Regular: Red Green Yellow Blue Magenta Cyan
- Bold:    Red Green Yellow Blue Magenta Cyan
- Dimmed:  Red Green Yellow Blue Magenta Cyan

256 colors (showing colors 160-177):
160 161 162 163 164 165
166 167 168 169 170 171
172 173 174 175 176 177

Full RGB colors:
ForestGreen - RGB(34, 139, 34)

Text formatting: Bold Dimmed Italic Underline

Supported languages

Out of the box, over 100 languages are supported, including JavaScript, TypeScript, HTML, CSS, Astro, Markdown, MDX, JSON, YAML, and many more. You can find a list of all language identifiers on GitHub.

Tip

You can support more languages by providing their grammars to the langs option. See the configuration section for examples on how to do this.

Differences to Shiki’s HTML output

If you’re migrating an existing site to Expressive Code that uses custom CSS to modify syntax-highlighted code, please note that the HTML output and classes generated by Expressive Code do not match the default output generated by Shiki.

Instead, the syntax tokens generated by Shiki are converted to Expressive Code’s own annotations (InlineStyleAnnotation), which provide efficient multi-theme support and can be combined with other annotations.

If you need additional classes on some HTML elements, consider writing your own plugin to modify the output as needed.

Configuration

When using this plugin through a framework integration, you can configure it by passing options to the integration.

Here are configuration examples for common scenarios:

Astro

astro.config.mjs

import { defineConfig } from 'astro/config'
import astroExpressiveCode from 'astro-expressive-code'
// Add this if you want to load a custom language grammar from a file:
// import fs from 'node:fs'

export default defineConfig({
  integrations: [
    astroExpressiveCode({
      // You can use any of the themes bundled with Shiki by name,
      // specify a path to JSON theme file, or pass an instance
      // of the `ExpressiveCodeTheme` class here:
      themes: ['dracula', 'solarized-light'],
      shiki: {
        // You can pass additional plugin options here,
        // e.g. to load custom language grammars:
        langs: [
          // import('./some-exported-grammar.mjs'),
          // JSON.parse(fs.readFileSync('./some-json-grammar.json', 'utf-8'))
        ],
      },
    }),
  ],
})

Starlight

astro.config.mjs

import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'
// Add this if you want to load a custom language grammar from a file:
// import fs from 'node:fs'

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Starlight site',
      expressiveCode: {
        // You can use any of the themes bundled with Shiki by name,
        // specify a path to JSON theme file, or pass an instance
        // of the `ExpressiveCodeTheme` class here:
        themes: ['dracula', 'solarized-light'],
        shiki: {
          // You can pass additional plugin options here,
          // e.g. to load custom language grammars:
          langs: [
            // import('./some-exported-grammar.mjs'),
            // JSON.parse(fs.readFileSync('./some-json-grammar.json', 'utf-8'))
          ],
        },
      },
    }),
  ],
})

Next.js

next.config.mjs

import createMDX from '@next/mdx'
import rehypeExpressiveCode from 'rehype-expressive-code'
// Add this if you want to load a custom language grammar from a file:
// import fs from 'node:fs'

/** @type {import('rehype-expressive-code').RehypeExpressiveCodeOptions} */
const rehypeExpressiveCodeOptions = {
  // You can use any of the themes bundled with Shiki by name,
  // specify a path to JSON theme file, or pass an instance
  // of the `ExpressiveCodeTheme` class here:
  themes: ['dracula', 'solarized-light'],
  shiki: {
    // You can pass additional plugin options here,
    // e.g. to load custom language grammars:
    langs: [
      // import('./some-exported-grammar.mjs'),
      // JSON.parse(fs.readFileSync('./some-json-grammar.json', 'utf-8'))
    ],
  },
}

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  pageExtensions: ["js", "jsx", "ts", "tsx", "md", "mdx"],
}

const withMDX = createMDX({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins: [],
    rehypePlugins: [
      // The nested array structure is required to pass options
      // to a rehype plugin
      [rehypeExpressiveCode, rehypeExpressiveCodeOptions],
    ],
  },
})

export default withMDX(nextConfig)

Available plugin options

You can pass the following options to the plugin:

langs

Type: LanguageInput[] Default: []

A list of additional languages that should be available for syntax highlighting.

You can pass any of the language input types supported by Shiki, e.g.:

• import('./some-exported-grammar.mjs')
• JSON.parse(fs.readFileSync('./some-json-grammar.json', 'utf-8'))

See the Shiki documentation for more information.

Caution

When using this option, Expressive Code automatically ensures that all bundled default languages are still available. You should not add Shiki’s bundledLanguages manually to this array, as this would load many unused languages and slow down both the dev server and build times.

injectLangsIntoNestedCodeBlocks

Type: boolean Default: false

By default, the additional languages defined in langs are only available in top-level code blocks contained directly in their parent Markdown or MDX document.

Setting this option to true also enables syntax highlighting when a fenced code block using one of your additional langs is nested inside an outer markdown, md or mdx code block. Example:

````md
This top-level Markdown code block contains a nested `my-custom-lang` code block:
```my-custom-lang
This nested code block will only be highlighted using `my-custom-lang`
if `injectLangsIntoNestedCodeBlocks` is enabled.
```
````

transformers

Type: ShikiTransformer[] Default: []

An optional list of Shiki transformers that should be called during syntax highlighting.

This option allows you to add transformers that modify the tokens produced by Shiki to improve syntax highlighting, e.g. by applying bracket matching or changing the color of certain tokens.

Experimental option with very limited support

This option currently only supports transformers that meet all of the following criteria:

• They do not contain any hooks except preprocess and tokens.
• They do not attempt to modify the text contents of a code block.

As a result, most popular transformers will not work, including @shikijs/transformers and @shikijs/twoslash, and attempting to add them will throw an error. This is expected behavior to inform you about the current limitations, and not a bug in any of the involved projects. Please do not report such errors to other authors, as they will be unable to help.

The current limitations exist because Expressive Code’s architecture is not yet compatible with Shiki’s transformers API, which has been introduced long after the release of Expressive Code. We will improve the supported transformer features in future releases to close the gap.

Tip

If you have a transformer that does useful work in its preprocess and tokens hooks without modifying any text contents, but it gets rejected by Expressive Code due to other hooks being present, you can create a custom transformer that wraps the original transformer and only exposes the supported hooks.

Using another syntax highlighter

If you want to use another syntax highlighter, you can set shiki: false in the configuration to prevent the default highlighter from being loaded. You can then write a plugin for the new syntax highlighter and add it to the plugins array.

Tip

If you publish your own plugin package to NPM, please let us know on GitHub. We’d love to showcase high-quality community plugins.