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
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.
meta
-
get meta(): string
-
set meta(value): void
Allows getting or setting the code block’s meta string. In markdown or MDX documents, this is the part of the code block’s opening fence that comes after the language name.
Setting this property may throw an error if not allowed in the current state.
Parameters
Parameter | Type |
---|---|
value | string |
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
string
The plaintext contents of the code block.
language
string
The code block’s language.
Please use a valid language identifier to ensure proper syntax highlighting.
locale?
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?
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?
Object
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.
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 thehast
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?
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
string
colors
Object
(mapping VS Code workbench color keys to values) fg
string
name
string
semanticHighlighting
boolean
settings
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
"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.
After adding this plugin to your configuration, you can use it like this:
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):
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.
Referenced types
AnnotationBaseOptions
Object
Object properties
- inlineRange
- renderPhase
- Type:
AnnotationRenderPhase
AnnotationRenderOptions
ResolverContext
& Object
Object properties
- line
- Type:
ExpressiveCodeLine
- lineIndex
- Type:
number
- nodesToTransform
- Type:
Parents
[]
AnnotationRenderPhase
"earliest"
| "earlier"
| "normal"
| "later"
| "latest"
ChromaticRecolorTarget
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.
ExpressiveCodeInlineRange
Object
Object properties
- columnEnd
- Type:
number
- columnStart
- Type:
number
ExpressiveCodeProcessingState
Properties
canEditAnnotations
boolean
canEditCode
boolean
canEditLanguage
boolean
canEditMetadata
boolean
InlineStyleAnnotationOptions
AnnotationBaseOptions
& Object
Object properties
- 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.
- 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
ExpressiveCodeBlockOptions
| ExpressiveCodeBlock
| (ExpressiveCodeBlockOptions
| ExpressiveCodeBlock
)[] RenderOptions
Properties
onInitGroup?
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
Object
Object properties
- settings
- Type:
Object
- settings.fontStyle
- Type:
string
- settings.foreground
- Type:
string
- name
- Type:
string
- scope
- Type:
string
[]