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[]

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.

Note

When using this option, Expressive Code automatically ensures that all bundled default languages are still available. You don’t need to add Shiki’s bundledLanguages manually to this array.

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.