Core API

Engine

ExpressiveCodeEngine

The Expressive Code engine is responsible for rendering code blocks to a Hypertext Abstract Syntax Tree (HAST) that can be serialized to HTML, as well as generating the required CSS styles and JS modules.

It also provides read-only access to all resolved configuration options through its public properties.

Constructors

new ExpressiveCodeEngine(config)

new ExpressiveCodeEngine(config): ExpressiveCodeEngine

Creates a new instance of the Expressive Code engine.

To minimize overhead caused by loading plugins, you can create a single instance for your application and keep using it to render all your code blocks.

Arguments

Parameter	Type
`config`	`ExpressiveCodeEngineConfig`

Methods

getBaseStyles()

getBaseStyles(): Promise<string>

Returns a string containing all CSS styles that should be added to every page using Expressive Code. These styles are static base styles which do not depend on the configured theme(s).

The calling code must take care of actually adding the returned styles to the page.

Please note that the styles contain references to CSS variables, which must also be added to the page. These can be obtained by calling getThemeStyles.

getJsModules()

getJsModules(): Promise<string[]>

Returns an array of JavaScript modules (pure code without any wrapping script tags) that should be added to every page containing code blocks.

The contents are collected from the jsModules property of all registered plugins. Any duplicates are removed.

The calling code must take care of actually adding the collected scripts to the page. For example, it could create site-wide JavaScript files from the returned modules and refer to them in a script tag with type="module", or it could insert them into inline <script type="module"> elements.

getThemeStyles()

getThemeStyles(): Promise<string>

Returns a string containing theme-dependent styles that should be added to every page using Expressive Code. These styles contain CSS variable declarations that are generated automatically based on the configured themes, useDarkModeMediaQuery and themeCssSelector config options.

The first theme defined in the themes option is considered the “base theme”, for which a full set of CSS variables is declared and scoped to the selector defined by the themeCssRoot option (defaults to :root).

For all alternate themes, a differential set of CSS variables is declared for cases where their values differ from the base theme, and scoped to theme-specific selectors that are generated by combining themeCssRoot with the theme selector specified by this option.

The calling code must take care of actually adding the returned styles to the page.

Please note that these styles must be added to the page together with the base styles returned by getBaseStyles.

render()

render(input, options?): Promise<Object>

Renders the given code block(s) and returns the rendered group & block ASTs, the rendered code block contents after all transformations have been applied, and a set of non-global CSS styles required by the rendered code blocks.

In Expressive Code, all processing of your code blocks and their metadata is performed by plugins. To render markup around lines or inline ranges of characters, the render method calls the hook functions registered by all added plugins.

Arguments

Parameter	Type	Description
`input`	`RenderInput`	The code block(s) to render. Can either be an `ExpressiveCodeBlockOptions` object containing the properties required to create a new `ExpressiveCodeBlock` internally, an existing `ExpressiveCodeBlock`, or an array containing any combination of these.
`options`?	`RenderOptions`	Optional configuration options for the rendering process.

Returns

Promise<Object>

renderedGroupAst: Type: Element
renderedGroupContents: Type: RenderedGroupContents
styles: Type: Set<string>

Properties

All config options that can be passed to the constructor are also available on the instance as read-only properties.

Code blocks

ExpressiveCodeBlock

Represents a single code block that can be rendered by the Expressive Code engine.

Usage example

import { ExpressiveCodeBlock } from 'expressive-code'

const codePlaintext = `
// Perform very important calculations
const a = 1 + 2
`

const codeBlock = new ExpressiveCodeBlock({
  code: codePlaintext.trim(),
  language: 'js',
})

// Delete the first line and output the remaining code
codeBlock.deleteLine(0)
console.dir(codeBlock.code)
// --> 'const a = 1 + 2'

Constructors

new ExpressiveCodeBlock(options)

new ExpressiveCodeBlock(options): ExpressiveCodeBlock

Arguments

Parameter	Type
`options`	`ExpressiveCodeBlockOptions`

Methods

deleteLine()

deleteLine(index): void

Deletes the line at the given index.

May throw an error if not allowed in the current state.

Arguments

Parameter	Type
`index`	`number`

deleteLines()

deleteLines(indices): void

Deletes the lines at the given indices.

This function automatically sorts the indices in descending order before deleting the lines, so you do not need to worry about indices shifting after deleting a line.

May throw an error if not allowed in the current state.

Arguments

Parameter	Type
`indices`	`number`[]

getLine()

getLine(index): undefined | ExpressiveCodeLine

Returns the line at the given index, or undefined if the index is out of range.

Arguments

Parameter	Type
`index`	`number`

getLines()

getLines(startIndex?, endIndex?): readonly ExpressiveCodeLine[]

Returns a readonly array of lines starting at the given index and ending before the given index (exclusive). The indices support the same syntax as JavaScript’s Array.slice method.

Arguments

Parameter	Type
`startIndex`?	`number`
`endIndex`?	`number`

insertLine()

insertLine(index, textLine): ExpressiveCodeLine

Inserts a new line at the given index.

May throw an error if not allowed in the current state.

Arguments

Parameter	Type
`index`	`number`
`textLine`	`string`

insertLines()

insertLines(index, textLines): ExpressiveCodeLine[]

Inserts multiple new lines at the given index.

May throw an error if not allowed in the current state.

Arguments

Parameter	Type
`index`	`number`
`textLines`	`string`[]

Accessors

code

get code(): string

Provides read-only access to the code block’s plaintext contents.

language

get language(): string
set language(value): void

Allows getting and setting the code block’s language.

Setting this property may throw an error if not allowed in the current state.

Parameters

Parameter	Type
`value`	`string`

locale

get locale(): undefined | string

Allows getting the code block’s locale (e.g. en-US or de-DE). It is used by plugins to display localized strings depending on the language of the containing page.

Integrations like rehype-expressive-code support multi-language sites by allowing you to provide custom logic to determine a block’s locale (e.g. based on its parent document).

If no locale is defined here, ExpressiveCodeEngine will render the code block using the defaultLocale provided in its configuration.

metaOptions

get metaOptions(): MetaOptions

Provides read-only access to the parsed version of the block’s meta string.

parentDocument

get parentDocument(): undefined | Object

Provides read-only access to optional data about the parent document the code block is located in.

Integrations like rehype-expressive-code can provide this information based on the source document being processed. There may be cases where no document is available, e.g. when the code block was created dynamically.

props

get props(): Partial<ExpressiveCodeBlockProps>

Provides access to the code block’s props.

To allow users to set these props through the meta string, plugins can use the preprocessMetadata hook to read metaOptions and update their props accordingly.

Props can be modified until rendering starts and become read-only afterwards.

state

get state(): undefined | ExpressiveCodeProcessingState

Provides read-only access to the code block’s processing state.

The processing state controls which properties of the code block can be modified. The engine updates it automatically during rendering.

ExpressiveCodeBlockOptions

Properties

code

Type: string

The plaintext contents of the code block.

language

Type: string

The code block’s language.

Please use a valid language identifier to ensure proper syntax highlighting.

locale?

Type: string

The code block’s locale (e.g. en-US or de-DE). This is used by plugins to display localized strings depending on the language of the containing page.

If no locale is defined here, most Expressive Code integrations will attempt to auto-detect the block locale using the configured getBlockLocale function, and finally fall back to the configured defaultLocale.

meta?

Type: string

An optional meta string. In markdown or MDX documents, this is the part of the code block’s opening fence that comes after the language name.

parentDocument?

Type: Object

Optional data about the parent document the code block is located in.

Object properties

documentRoot

Type: unknown

A reference to the object representing the parsed source document. This reference will stay the same for all code blocks in the same document.

For example, if you are using rehype-expressive-code to render code blocks in a Markdown file, this would be the hast node representing the file’s root node.

positionInDocument

Type: Object

Data about the position of the code block in the parent document.

positionInDocument.groupIndex

Type: number

positionInDocument.totalGroups

Type: number

sourceFilePath

Type: string

The full path to the source file containing the code block.

props?

Type: Partial<ExpressiveCodeBlockProps>

Optional props that can be used to influence the rendering of this code block.

Plugins can add their own props to this type. To allow users to set these props through the meta string, plugins can use the preprocessMetadata hook to read metaOptions and update the props object accordingly.

ExpressiveCodeLine

Constructors

new ExpressiveCodeLine(text)

new ExpressiveCodeLine(text): ExpressiveCodeLine

Arguments

Parameter	Type
`text`	`string`

Methods

addAnnotation()

addAnnotation(annotation): void

Arguments

Parameter	Type
`annotation`	`ExpressiveCodeAnnotation`

deleteAnnotation()

deleteAnnotation(annotation): void

Arguments

Parameter	Type
`annotation`	`ExpressiveCodeAnnotation`

editText()

editText(columnStart, columnEnd, newText): string

Arguments

Parameter	Type
`columnStart`	`undefined` \| `number`
`columnEnd`	`undefined` \| `number`
`newText`	`string`

getAnnotations()

getAnnotations(): readonly ExpressiveCodeAnnotation[]

Accessors

parent

get parent(): undefined | ExpressiveCodeBlock
set parent(value): void

Parameters

Parameter	Type
`value`	`undefined` \| `ExpressiveCodeBlock`

text

get text(): string

MetaOptions

Constructors

new MetaOptions(input)

new MetaOptions(input): MetaOptions

Arguments

Parameter	Type
`input`	`string`

Methods

getBoolean()

getBoolean(key): undefined | boolean

Returns the last boolean value with the given key (case-insensitive).

Arguments

Parameter	Type
`key`	`string`

getInteger()

getInteger(key): undefined | number

Returns the last integer value with the given key (case-insensitive), or without a key by passing an empty string.

Arguments

Parameter	Type
`key`	`string`

getIntegers()

getIntegers(keyOrKeys?): number[]

Returns an array of all integer values with the given keys (case-insensitive), or without a key by passing an empty string.

Arguments

Parameter	Type
`keyOrKeys`?	`string` \| `string`[]

getRange()

getRange(key): undefined | string

Returns the last range value ({value}) with the given key (case-insensitive), or without a key by passing an empty string.

Arguments

Parameter	Type
`key`	`string`

getRanges()

getRanges(keyOrKeys?): string[]

Returns an array of all range values ({value}) with the given keys (case-insensitive), or without a key by passing an empty string.

Arguments

Parameter	Type
`keyOrKeys`?	`string` \| `string`[]

getRegExp()

getRegExp(key): undefined | RegExp

Returns the last RegExp value (/value/) with the given key (case-insensitive), or without a key by passing an empty string.

Arguments

Parameter	Type
`key`	`string`

getRegExps()

getRegExps(keyOrKeys?): RegExp[]

Returns an array of all RegExp values (/value/) with the given keys (case-insensitive), or without a key by passing an empty string.

Arguments

Parameter	Type
`keyOrKeys`?	`string` \| `string`[]

getString()

getString(key): undefined | string

Returns the last string value with the given key (case-insensitive), or without a key by passing an empty string.

Arguments

Parameter	Type
`key`	`string`

getStrings()

getStrings(keyOrKeys?): string[]

Returns an array of all string values with the given keys (case-insensitive), or without a key by passing an empty string.

Arguments

Parameter	Type
`keyOrKeys`?	`string` \| `string`[]

list()

list<K>(keyOrKeys?, kind?): ReturnType

Returns a list of meta options, optionally filtered by their key and/or MetaOptionKind.

Type parameters

Parameter	Value
`K` extends `undefined` \| `"string"` \| `"boolean"` \| `"range"` \| `"regexp"`	`undefined`

Arguments

Parameter	Type	Description
`keyOrKeys`?	`string` \| `string`[]	Allows to filter the options by key. An empty string will return options without a key. A non-empty string will return options with a matching key (case-insensitive). An array of strings will return options with any of the matching keys. If omitted, no key-based filtering will be applied.
`kind`?	`K`	Allows to filter the options by MetaOptionKind. If omitted, no kind-based filtering will be applied.

value()

value<K>(key, kind?): undefined | OptionType[“value”]

Type parameters

Parameter	Value
`K` extends `undefined` \| `"string"` \| `"boolean"` \| `"range"` \| `"regexp"`	`undefined`

Arguments

Parameter	Type
`key`	`string`
`kind`?	`K`

Accessors

errors

get errors(): undefined | string[]

A list of error messages that occurred when parsing the meta string, or undefined if no errors occurred.

Themes

ExpressiveCodeTheme

Constructors

new ExpressiveCodeTheme(theme)

new ExpressiveCodeTheme(theme): ExpressiveCodeTheme

Loads the given theme for use with Expressive Code. Supports both Shiki and VS Code themes.

You can also pass an existing ExpressiveCodeTheme instance to create a copy of it.

Note: To save on bundle size, this constructor does not support loading themes bundled with Shiki by name (e.g. dracula). Instead, import Shiki’s loadTheme function yourself, use it to load its bundled theme (e.g. themes/dracula.json), and pass the result to this constructor.

Arguments

Parameter	Type
`theme`	`ExpressiveCodeThemeInput`

Methods

applyHueAndChromaAdjustments()

applyHueAndChromaAdjustments(adjustments): ExpressiveCodeTheme

Applies chromatic adjustments to entire groups of theme colors while keeping their relative lightness and alpha components intact. This can be used to quickly create theme variants that fit the color scheme of any website or brand.

Adjustments can either be defined as hue and chroma values in the OKLCH color space (range 0–360 for hue, 0–0.4 for chroma), or these values can be extracted from hex color strings (e.g. #3b82f6).

You can target predefined groups of theme colors (e.g. backgrounds, accents) and/or use the custom property to define your own groups of theme colors to be adjusted. Each custom group must contain a themeColorKeys property with an array of VS Code theme color keys (e.g. ['panel.background', 'panel.border']) and a targetHueAndChroma property that accepts the same adjustment target values as backgrounds and accents. Custom groups will be applied in the order they are defined.

Returns the same ExpressiveCodeTheme instance to allow chaining.

Arguments

Parameter	Type
`adjustments`	`Object`
`adjustments.accents`?	`string` \| `ChromaticRecolorTarget`
`adjustments.backgrounds`?	`string` \| `ChromaticRecolorTarget`
`adjustments.custom`?	`Object`[]

ensureMinSyntaxHighlightingColorContrast()

ensureMinSyntaxHighlightingColorContrast(minContrast, backgroundColor?): ExpressiveCodeTheme

Processes the theme’s syntax highlighting colors to ensure a minimum contrast ratio between foreground and background colors.

The default value of 5.5 ensures optimal accessibility with a contrast ratio of 5.5:1.

You can optionally pass a custom background color to use for the contrast checks. By default, the theme’s background color will be used.

Returns the same ExpressiveCodeTheme instance to allow chaining.

Arguments

Parameter	Type	Default value
`minContrast`	`number`	`5.5`
`backgroundColor`?	`string`	`undefined`

fromJSONString()

static fromJSONString(json): ExpressiveCodeTheme

Attempts to parse the given JSON string as a theme.

As some themes follow the JSONC format and may contain comments and trailing commas, this method will attempt to strip them before parsing the result.

Arguments

Parameter	Type
`json`	`string`

Properties

bg

Type: string

colors

Type: Object (mapping VS Code workbench color keys to values)

fg

Type: string

name

Type: string

semanticHighlighting

Type: boolean

settings

Type: ThemeSetting[]

styleOverrides

An optional set of style overrides that can be used to customize the appearance of the rendered code blocks without having to write custom CSS.

See Overriding Styles for a list of all available settings.

type

Type: "dark" | "light"

Annotations

In Expressive Code, annotations are used by plugins to attach semantic information to lines or inline ranges of code. They are used to represent things like syntax highlighting, text markers, comments, errors, warnings, and other semantic information.

Annotations must provide a render function that transforms its contained AST nodes, e.g. by wrapping them in HTML tags. This function is called by the engine when it’s time to render the line the annotation has been attached to.

ExpressiveCodeAnnotation

An abstract class representing a single annotation attached to a code line.

You can develop your own annotations by extending this class and providing implementations for its abstract methods. See the implementation of the InlineStyleAnnotation class for an example.

You can also define your annotations as plain objects, as long as they have the same properties as this class. This allows you to use annotations in a more functional way, without the need to extend a class.

Constructors

Methods

`abstract` render()

abstract render(options): Parents[]

Renders the annotation by transforming the provided nodes.

This function will be called with an array of AST nodes to transform, and is expected to return an array containing the same number of nodes.

For example, you could use the hastscript library to wrap the received nodes in HTML elements.

Arguments

Parameter	Type
`options`	`AnnotationRenderOptions`

Properties

All annotation base options are available on the instance as read-only properties. See AnnotationBaseOptions for the entire list.

InlineStyleAnnotation

A theme-dependent inline style annotation that allows changing colors, font styles and decorations of the targeted code. This annotation is used by the syntax highlighting plugin to apply colors and styles to syntax tokens, and you can use it in your own plugins as well.

You can add as many inline style annotations to a line as you want, even targeting the same code with multiple fully or partially overlapping annotation ranges. During rendering, these annotations will be automatically optimized to avoid creating unnecessary HTML elements.

Usage example

In the following example, we create a plugin that makes the first word of each code block red in the first theme. We do this by adding an InlineStyleAnnotation to the first line of each code block.

// @ts-check
import { definePlugin, InlineStyleAnnotation } from '@expressive-code/core'

export function pluginFirstWordRed() {
  return definePlugin({
    name: 'Make first word red',
    hooks: {
      postprocessAnalyzedCode: (context) => {
        // Only apply this to code blocks with the `first-word-red` meta
        if (!context.codeBlock.meta.includes('first-word-red')) return

        // Get the first line of the code block
        const firstLine = context.codeBlock.getLine(0)
        if (!firstLine) return

        // Find the end of the first word
        const firstWordEnd = firstLine.text.match(/(?<=\w)\W/)?.index ?? -1
        if (firstWordEnd <= 0) return

        // Add an annotation that makes the first word red
        firstLine.addAnnotation(
          new InlineStyleAnnotation({
            inlineRange: {
              columnStart: 0,
              columnEnd: firstWordEnd,
            },
            color: '#ff0000',
            // Only apply the red color to the first configured theme
            styleVariantIndex: 0,
          })
        )
      },
    },
  })
}

After adding this plugin to your configuration, you can use it like this:

```js first-word-red
consule.log('Hello world!')
```

The rendered code block will now have a red text color applied to the first word, but only in the dark theme (the first theme in the configuration):

consule.log('Hello world!')

Constructors

new InlineStyleAnnotation(options)

new InlineStyleAnnotation(options): InlineStyleAnnotation

Arguments

Parameter	Type
`options`	`InlineStyleAnnotationOptions`

Methods

render()

render(options): Parents[]

Renders the annotation by transforming the provided nodes.

This function will be called with an array of AST nodes to transform, and is expected to return an array containing the same number of nodes.

For example, you could use the hastscript library to wrap the received nodes in HTML elements.

Arguments

Parameter	Type
`options`	`AnnotationRenderOptions`

Properties

All config options that can be passed to the constructor are also available on the instance as read-only properties.

See InlineStyleAnnotationOptions for the entire list.

Asset functions

createInlineSvgUrl

createInlineSvgUrl(svgContents, options): string

Creates an inline SVG image data URL from the given contents of an SVG file.

You can use it to embed SVG images directly into a plugin’s styles or HAST, or pass it to an existing styleOverrides icon setting.

The optional options argument allows further customization of the generated URL.

Arguments

Parameter	Type
`svgContents`	`string` \| `string`[]
`options`	`CreateInlineSvgUrlOptions`

Color analysis functions

getColorContrast

getColorContrast(color1, color2): number

Arguments

Parameter	Type
`color1`	`string`
`color2`	`string`

getColorContrastOnBackground

getColorContrastOnBackground(input, background): number

Arguments

Parameter	Type
`input`	`string`
`background`	`string`

getFirstStaticColor

getFirstStaticColor(…inputs): undefined | string

Given any number of input colors, which may include CSS variables with optional fallbacks, returns the first static color.

Returns undefined if no parseable static color can be found.

Arguments

Parameter	Type
…`inputs`	(`undefined` \| `string`)[]

getLuminance

getLuminance(input): number

Returns the luminance of a color. Luminance values are between 0 and 1.

Arguments

Parameter	Type
`input`	`string`

getStaticBackgroundColor

getStaticBackgroundColor(styleVariant): string

Determine a static background color based on the given style variant, trying to resolve fallback values of CSS variables if necessary.

This color is intended to be used for contrast calculations, not as an actual background color.

Arguments

Parameter	Type
`styleVariant`	`StyleVariant`

Color manipulation functions

changeAlphaToReachColorContrast

changeAlphaToReachColorContrast(input, background, minContrast, maxContrast): string

Arguments

Parameter	Type	Default value
`input`	`string`	`undefined`
`background`	`string`	`undefined`
`minContrast`	`number`	`6`
`maxContrast`	`number`	`22`

changeLuminanceToReachColorContrast

changeLuminanceToReachColorContrast(input1, input2, minContrast): string

Arguments

Parameter	Type	Default value
`input1`	`string`	`undefined`
`input2`	`string`	`undefined`
`minContrast`	`number`	`6`

darken

darken(input, amount): string

Darkens a color by the given amount. Automatically limits the resulting lightness value to the range 0 to 1.

Arguments

Parameter	Type
`input`	`string`
`amount`	`number`

ensureColorContrastOnBackground

ensureColorContrastOnBackground(input, background, minContrast, maxContrast): string

Modifies the luminance and/or the alpha value of a color to ensure its color contrast on the given background color is within the given range.

If the contrast is too low, the luminance is either increased or decreased first, and then the alpha value is increased (if required).
If the contrast is too high, only the alpha value is decreased.

If the target contrast cannot be reached, the function will try to get as close as possible.

Arguments

Parameter	Type	Default value
`input`	`string`	`undefined`
`background`	`string`	`undefined`
`minContrast`	`number`	`5.5`
`maxContrast`	`number`	`22`

lighten

lighten(input, amount): string

Lightens a color by the given amount. Automatically limits the resulting lightness value to the range 0 to 1.

Arguments

Parameter	Type
`input`	`string`
`amount`	`number`

mix

mix(input, mixinInput, amount): string

Mixes the second color into the first color by the given amount. Amount should be between 0 and 1.

Arguments

Parameter	Type
`input`	`string`
`mixinInput`	`string`
`amount`	`number`

multiplyAlpha

multiplyAlpha(input, factor): string

Multiplies the existing alpha value of a color with the given factor. Automatically limits the resulting alpha value to the range 0 to 1.

Arguments

Parameter	Type
`input`	`string`
`factor`	`number`

onBackground

onBackground(input, background): string

Computes how the first color would look on top of the second color.

Arguments

Parameter	Type
`input`	`string`
`background`	`string`

setAlpha

setAlpha(input, newAlpha): string

Overrides the alpha value of a color with the given value. Values should be between 0 and 1.

Arguments

Parameter	Type
`input`	`string`
`newAlpha`	`number`

setLuminance

setLuminance(input, targetLuminance): string

Mixes a color with white or black to achieve the desired luminance. Luminance values should be between 0 and 1.

Arguments

Parameter	Type
`input`	`string`
`targetLuminance`	`number`

Referenced types

AnnotationBaseOptions

Type: Object

Object properties

inlineRange: Type: ExpressiveCodeInlineRange
renderPhase: Type: AnnotationRenderPhase

AnnotationRenderOptions

Type: ResolverContext & Object

Object properties

line: Type: ExpressiveCodeLine
lineIndex: Type: number
nodesToTransform: Type: Parents[]

AnnotationRenderPhase

Type: "earliest" | "earlier" | "normal" | "later" | "latest"

ChromaticRecolorTarget

Type: Object

Object properties

chroma

Type: number

The target chroma (0 – 0.4).

If the input color’s lightness is very high, the resulting chroma may be lower than this value. This avoids results that appear too saturated in comparison to the input color.

hue

Type: number

The target hue in degrees (0 – 360).

chromaMeasuredAtLightness

Type: number

The lightness (0 – 1) that the target chroma was measured at.

If given, the chroma will be adjusted relative to this lightness before applying it to the input color.

CreateInlineSvgUrlOptions

Type: Object

Object properties

keepSize

Type: boolean

Whether to keep the original size of the SVG image.

By default, any width and height attributes inside the SVG tag are removed.

ExpressiveCodeInlineRange

Type: Object

Object properties

columnEnd: Type: number
columnStart: Type: number

ExpressiveCodeProcessingState

Properties

canEditAnnotations

Type: boolean

canEditCode

Type: boolean

canEditLanguage

Type: boolean

canEditMetadata

Type: boolean

InlineStyleAnnotationOptions

Type: AnnotationBaseOptions & Object

Object properties

bgColor

Type: string

The background color of the annotation. This is expected to be a hex color string, e.g. #888. Using CSS variables or other color formats is possible, but prevents automatic color contrast checks from working.

bold

Type: boolean

Whether the annotation should be rendered in bold.

color

Type: string

The color of the annotation. This is expected to be a hex color string, e.g. #888. Using CSS variables or other color formats is possible, but prevents automatic color contrast checks from working.

italic

Type: boolean

Whether the annotation should be rendered in italics.

strikethrough

Type: boolean

Whether the annotation should be rendered with a strikethrough.

styleVariantIndex

Type: number

Inline styles can be theme-dependent, which allows plugins like syntax highlighters to style the same code differently depending on the theme.

To support this, the engine creates a style variant for each theme given in the configuration, and plugins can go through the engine’s styleVariants array to access all the themes.

When adding an inline style annotation to a range of code, you can optionally set this property to a styleVariants array index to indicate that this annotation only applies to a specific theme. If this property is not set, the annotation will apply to all themes.

underline

Type: boolean

Whether the annotation should be rendered with an underline.

RenderInput

Type: ExpressiveCodeBlockOptions | ExpressiveCodeBlock | (ExpressiveCodeBlockOptions | ExpressiveCodeBlock)[]

RenderOptions

Properties

onInitGroup?

Type: (groupContents) => void

An optional handler function that can initialize plugin data for the code block group before processing starts.

Plugins can provide access to their data by exporting a const set to a new AttachedPluginData(...) instance (e.g. myPluginData).

You can then import the const and set onInitGroup to a function that calls myPluginData.setFor(group, { ...data... }).

Arguments

Parameter	Type
`groupContents`	readonly { `codeBlock`: `ExpressiveCodeBlock` }[]

ThemeSetting

Type: Object

Object properties

settings: Type: Object
settings.fontStyle: Type: string
settings.foreground: Type: string
name: Type: string
scope: Type: string[]