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
Standard ANSI colors:
- Dimmed:      Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
- Foreground:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
- Background:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
- Reversed:    Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 

8-bit colors (showing colors 160-171 as an example):
- Dimmed:      160  161  162  163  164  165  166  167  168  169  170  171 
- Foreground:  160  161  162  163  164  165  166  167  168  169  170  171 
- Background:  160  161  162  163  164  165  166  167  168  169  170  171 
- Reversed:    160  161  162  163  164  165  166  167  168  169  170  171 

24-bit colors (full RGB):
- Dimmed:      ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
- Foreground:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
- Background:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
- Reversed:    ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 

Font styles:
- Default
- Bold
- Dimmed
- Italic
- Underline
- Reversed
- Strikethrough
```

Result:

Standard ANSI colors:
- Dimmed:      Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
- Foreground:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
- Background:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
- Reversed:    Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 

8-bit colors (showing colors 160-171 as an example):
- Dimmed:      160  161  162  163  164  165  166  167  168  169  170  171 
- Foreground:  160  161  162  163  164  165  166  167  168  169  170  171 
- Background:  160  161  162  163  164  165  166  167  168  169  170  171 
- Reversed:    160  161  162  163  164  165  166  167  168  169  170  171 

24-bit colors (full RGB):
- Dimmed:      ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
- Foreground:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
- Background:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
- Reversed:    ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 

Font styles:
- Default
- Bold
- Dimmed
- Italic
- Underline
- Reversed
- Strikethrough

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:

bundledLangs

Type: BundledShikiLanguage[] Default: undefined Availability: Astro and Starlight integrations only

Allows defining a subset of language IDs from the full Shiki bundle that should be available for syntax highlighting.

In server-side rendering (SSR) environments, setting this option to the languages used on your site can reduce bundle size by up to 80%.

If this option is not set, all languages from the full Shiki bundle are available.

Astro

astro.config.mjs

import { defineConfig } from 'astro/config'
import astroExpressiveCode from 'astro-expressive-code'
import cloudflare from '@astrojs/cloudflare'

export default defineConfig({
  integrations: [
    astroExpressiveCode({
      shiki: {
        // Example: Only include languages 'astro' and 'sass'
        // in the bundle, reducing SSR bundle size by 80%
        bundledLangs: ['astro', 'sass'],
      },
    }),
  ],
  // Server-side rendering (SSR) must be enabled
  // for bundle size trimming to have an effect
  output: 'server',
  adapter: cloudflare(),
})

Starlight

astro.config.mjs

import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'
import cloudflare from '@astrojs/cloudflare'

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Starlight site',
      expressiveCode: {
        shiki: {
          // Example: Only include languages 'astro' and 'sass'
          // in the bundle, reducing SSR bundle size by 80%
          bundledLangs: ['astro', 'sass'],
        },
      },
    }),
  ],
  // Server-side rendering (SSR) must be enabled
  // for bundle size trimming to have an effect
  output: 'server',
  adapter: cloudflare(),
})

engine

Type: 'oniguruma' | 'javascript' Default: 'oniguruma'

The Shiki RegExp engine to be used for syntax highlighting. The following options are available:

• 'oniguruma': The default engine that supports all grammars, but requires a target environment with WebAssembly (WASM) support.
• 'javascript': A pure JavaScript engine that does not require WASM. The Shiki team is continuously improving this engine and aims for full compatibility with the Oniguruma engine. Use this engine if your target environment does not support WASM.

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 the languages bundled with Shiki are still available, unless you have limited them using the bundledLangs option.

Therefore, please do not add Shiki’s bundled languages manually to this array, as this would load many unused languages and slow down both the dev server and build times.

langAlias

Type: Record<string, string>

Allows defining alias names for languages. The keys are the alias names, and the values are the language IDs to which they should resolve.

The values can either be bundled languages, or additional languages defined in langs.

Astro

astro.config.mjs

import { defineConfig } from 'astro/config'
import astroExpressiveCode from 'astro-expressive-code'

export default defineConfig({
  integrations: [
    astroExpressiveCode({
      shiki: {
        // Allow using the alias 'mjs' for the 'javascript' language
        langAlias: {
          mjs: 'javascript',
        },
      },
    }),
  ],
})

Starlight

astro.config.mjs

import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Starlight site',
      expressiveCode: {
        shiki: {
          // Allow using the alias 'mjs' for the 'javascript' language
          langAlias: {
            mjs: 'javascript',
          },
        },
      },
    }),
  ],
})

Next.js

next.config.mjs

import createMDX from '@next/mdx'
import rehypeExpressiveCode from 'rehype-expressive-code'

/** @type {import('rehype-expressive-code').RehypeExpressiveCodeOptions} */
const rehypeExpressiveCodeOptions = {
  shiki: {
    // Allow using the alias 'mjs' for the 'javascript' language
    langAlias: {
      mjs: 'javascript',
    },
  },
}

/** @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)

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.