Expressive Code Documentation

Expressive Code is a framework-agnostic tool designed to present source code on the web with high visual fidelity and ease of understanding.

Key features include:

• Full VS Code support: Accurate syntax highlighting and full VS Code theme support.
• Rich UI components: Includes editor and terminal frames, copy-to-clipboard functionality, text markers, and collapsible sections.
• Framework-agnostic: Zero dependencies on front-end frameworks like React or Vue. It is compatible with Astro, Next.js, plain Markdown, and MDX.
• Extensible: A plugin-based architecture that ships with default plugins and provides an API for custom extensions.
• Accessible: Designed for accessibility, ensuring proper color contrast and supporting dark mode, screen readers, and keyboard navigation.

Expressive Code is an engine for presenting source code on the web. It provides accurate syntax highlighting (powered by the same engine as VS Code) and allows for advanced annotations such as text markers, diff highlighting, and code editor or terminal window frames.

Key characteristics:

• Plugin-based architecture: Extend functionality with custom annotations.
• Framework agnostic: Does not depend on any client-side framework.
• Performance-oriented: Designed to be lightweight and fast.

The rehype-expressive-code package is a rehype plugin for the unified ecosystem. It allows you to automatically render code blocks within your Markdown or MDX documents using the features and design of Expressive Code.

Use this package when you want to enhance the visual design and functionality (such as syntax highlighting, line highlighting, and more) of all code blocks in a project that uses a rehype-compatible processing pipeline.

The @expressive-code/plugin-frames plugin is a default feature of Expressive Code that renders a window frame around every code block. The visual style of the frame adapts to the language of the code: it can appear as a code editor (resembling VS Code) or as a terminal window.

Because this is a default plugin, it is automatically included when using higher-level Expressive Code packages (like expressive-code or astro-expressive-code) and does not require manual installation.

@expressive-code/plugin-shiki is a default plugin for Expressive Code that provides syntax highlighting using Shiki. It uses the same engine as VS Code, supporting accurate highlighting for over 100 languages.

Installation: No manual installation is required if you are using higher-level Expressive Code packages (such as expressive-code or astro-expressive-code), as this plugin is installed by default.

Annotations attach semantic information (like errors or highlights) to lines or inline ranges of code. To create a custom annotation, extend the ExpressiveCodeAnnotation class and implement the render function. The render function transforms AST nodes (e.g., by wrapping them in HTML tags) when the engine renders the annotated line.

Important: If publishing a plugin, import ExpressiveCodeAnnotation from @expressive-code/core as a peer dependency.

If you are migrating a site that relies on custom CSS targeting Shiki's default HTML classes, be aware that Expressive Code's output differs.

Instead of standard Shiki classes, Expressive Code converts Shiki syntax tokens into its own InlineStyleAnnotation system. This approach enables efficient multi-theme support and allows tokens to be combined with other Expressive Code annotations. If you require specific HTML elements or classes, you should write a custom plugin to modify the output.

The expressive-code package is intended for advanced use cases, such as building custom integrations for other tools or frameworks.

If you simply want to render code blocks on a website, use a higher-level integration package instead:

• Use astro-expressive-code for Astro projects.
• Use rehype-expressive-code for rendering code blocks in Markdown or MDX documents.

A style setting value can be defined as a StyleValueOrValues. This type supports two formats:

1. string: A single static value used for all themes.
2. [string, string]: An array where the first element is used for dark themes and the second element is used for light themes.

// Static value
const color = 'red';

// Theme-specific values: [dark, light]
const themeColor: StyleValueOrValues = ['#ffffff', '#000000'];

Groups are collections of related code blocks defined by the calling code (e.g., a rehype plugin).

postprocessRenderedBlockGroup allows you to edit the ASTs of all code blocks within a group, as well as the AST of the group's root element.

Example Use Case: The frames plugin uses this hook to display multiple code blocks as editor file tabs.

Note: Even if a code block is not part of a group, this hook will still be called (standalone blocks are treated as a group containing a single block).