Plugin API
ExpressiveCodePlugin
An interface that defines an Expressive Code plugin. To add a custom plugin, you pass an object matching this interface into the plugins
array property of the engine configuration.
Properties
name
string
The display name of the plugin. This is the only required property. It is used by the engine to display messages concerning the plugin, e.g. when it encounters an error.
baseStyles?
string
| BaseStylesResolverFn
The CSS styles that should be added to every page containing code blocks.
All styles are scoped to Expressive Code by default, so they will not affect the rest of the page. SASS-like nesting is supported. If you want to add global styles, you can use the @at-root
rule or target :root
, html
or body
in your selectors.
The engine’s getBaseStyles
function goes through all registered plugins and collects their base styles.
If you provide a function instead of a string, it is called with an object argument of type ResolverContext, and is expected to return a string or a string promise.
The calling code must take care of actually adding the collected styles to the page. For example, it could create a site-wide CSS stylesheet from the base styles and insert a link to it, or it could insert the base styles into a <style>
element.
hooks?
A set of functions that should be called by the engine at specific points in the rendering process. See ExpressiveCodePluginHooks for a list of available hooks.
jsModules?
string
[] | JsModulesResolverFn
JavaScript modules (pure code without any wrapping script
tags) that should be added to every page containing code blocks.
The engine’s getJsModules
function goes through all registered plugins, collects their JS modules and deduplicates them.
If you provide a function instead of a string, it is called with an object argument of type ResolverContext, and is expected to return a string or a string promise.
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.
styleSettings?
PluginStyleSettings
An instance of PluginStyleSettings
that is used to define the plugin’s CSS variables.
PluginStyleSettings
Represents a strongly typed set of style settings provided by a plugin (or core).
The constructor expects an object with a defaultSettings
property. This property must contain the default values for all settings and will be made available as a public instance property. Allowed default value types are plain values (e.g. strings), an array of two values to provide a dark and light variant, or resolver functions that return one of these types.
If you are writing a plugin that provides style overrides, please merge your style overrides into the StyleOverrides
interface declaration provided by the @expressive-code/core
module. You can see an example of this below.
As a plugin author, you should also assign an instance of this class to your plugin’s
styleSettings
property. This allows the engine to automatically declare CSS variables for your style settings in all theme variants defined in the config.
To consume the CSS variables in your plugin’s baseStyles
or anywhere else, see the
cssVar method to get a CSS variable reference to any style setting.
If CSS variables should not be generated for some of your style settings, you can exclude them using the cssVarExclusions
property of the object passed to the constructor.
Example
Constructors
new PluginStyleSettings(options)
-
new PluginStyleSettings(options): PluginStyleSettings
Arguments
Parameter | Type |
---|---|
options | Object |
options.defaultValues | Partial <UnresolvedStyleSettings > |
options.cssVarExclusions ? | StyleSettingPath [] |
Properties
cssVarExclusions
StyleSettingPath
[] defaultValues
Partial
<UnresolvedStyleSettings
> AttachedPluginData
A class that allows plugins to attach custom data to objects like code blocks, and to optionally allow external access to this data in a type-safe manner.
Usage example
Type parameters
Parameter |
---|
PluginDataType |
Constructors
new AttachedPluginData(getInitialValueFn)
-
new AttachedPluginData<PluginDataType>(getInitialValueFn): AttachedPluginData<PluginDataType>
Arguments
Parameter | Type |
---|---|
getInitialValueFn | () => PluginDataType |
Methods
getOrCreateFor()
-
getOrCreateFor(target): PluginDataType
Arguments
Parameter | Type |
---|---|
target | PluginDataTarget |
setFor()
-
setFor(target, data): void
Arguments
Parameter | Type |
---|---|
target | PluginDataTarget |
data | PluginDataType |
Referenced types
BaseStylesResolverFn
context
) => string
| Promise
<string
> A function that you can assign to the baseStyles
property of an ExpressiveCodePlugin
.
The engine will call it when going through all registered plugins and collecting their base styles.
Arguments
Parameter | Type |
---|---|
context | ResolverContext |
JsModulesResolverFn
context
) => string
[] | Promise
<string
[]> A function that you can assign to the jsModules
property of an ExpressiveCodePlugin
.
The engine will call it when going through all registered plugins and collecting their JS modules.
Arguments
Parameter | Type |
---|---|
context | ResolverContext |
ResolverContext
Object
A context object that the engine passes to most hook functions.
It provides access to theme-dependent CSS variables, all resolved style variants based on the configured themes and settings, and the config-dependent wrapper class name.
Object properties
- cssVar
- Type: (
styleSetting
,fallbackValue
?) =>string
- cssVarName
- Type: (
styleSetting
) =>string
- styleVariants
- Type:
StyleVariant
[]
ResolvedStyleSettingsByPath
Map
<StyleSettingPath
, string
> StyleResolverFn
context
) => StyleValueOrValues
A function that resolves a single style setting to a StyleValueOrValues.
You can assign this to any style setting to dynamically generate style values based on the current theme.
This function is called once for each style variant in the engine’s styleVariants
array, which includes one entry per theme in the engine’s themes
configuration option.
Arguments
Parameter | Type | Description |
---|---|---|
context | Object | - |
context.resolveSetting | (settingPath ) => string | - |
context.styleVariantIndex | number | The index in the engine’s styleVariants array that’s currently being resolved. |
context.theme | ExpressiveCodeTheme | - |
StyleSettingPath
FlattenKeys
<StyleSettings
> StyleValueOrValues
string
| [string
, string
] The value of a single style setting. You can either set it to a string, or an array of two strings.
If you use the array form, the first value will be used for dark themes, and the second value for light themes.
StyleVariant
Object
Object properties
- cssVarDeclarations
- Type:
Map
<string
,string
> - resolvedStyleSettings
- theme
- Type:
ExpressiveCodeTheme
UnresolvedPluginStyleSettings
{ [SettingName in keyof T]: UnresolvedStyleValue }
Type parameters
Parameter |
---|
T |
UnresolvedStyleValue
StyleValueOrValues
| StyleResolverFn
This is the value type for all style overrides. It allows either static style values or a resolver function.
UnresolvedStyleSettings
{ [K in keyof StyleSettings]: StyleSettings[K] extends object ? UnresolvedPluginStyleSettings<StyleSettings[K]> : UnresolvedStyleValue }