Release Candidate: Marp Core v5 🌈

[yhatt]

I'm thrilled to announce that Marp Core has shipped the release candidate version v5.0.0!

Ahead of future stable release, let me introduce new features and breaking changes you should be aware of.

• 🧜 Mermaid diagrams
• 🖍️ New syntax highlighting
• 🪽 A lightweight core by default for developers

Important

v5 is not a stable release yet, and following features are NOT YET AVAILABLE in Marp CLI and Marp for VS Code. If you want to test v5 features in Marp CLI, please read Prepare for v5.

Mermaid diagrams - finally!

The request to support Mermaid diagrams in Marp dates back to 2016, about 10 years ago.

Although Mermaid and Markdown are a natural combination in today, reliably rendering Mermaid inside Marp has been a long-standing challenge. We could not confidently ship it as a core feature until achieve consistent and reliable rendering across different JS environments, server, client, worker, etc.

Marp Core v5 finally makes this possible, powered by using beautiful-mermaid to generate deterministic SVG diagrams.

```mermaid
graph LR
  M[Marpit framework] --> C{Marp Core}
  C --> CLI[Marp CLI]
  C --> VS[Marp for VS Code]
  C --> O[[Your own app]]
```

Supported diagrams

These are based on beautiful-mermaid:

• Flowcharts
• Sequence diagrams
• State diagrams
• Class diagrams
• Entity relationship diagrams (ERD)
• XY bar and line charts

Check out the Mermaid diagram documentation for details in Marp Core.

New syntax highlighting

Marp Core v5 introduces new syntax highlighting powered by Shiki.

Shiki uses TextMate grammars, as does VS Code. It provides accurate highlighting and broad language support. In most cases, the effect on appearance is very slight.

```js
import { Marp } from '@marp-team/marp-core';
import shiki from '@marp-team/marp-core/plugins/shiki';

const marp = new Marp().use(shiki());
const { html, css } = marp.render('# Hello, Marp!');
```

Line highlighting

v5 added a new feature to highlight specific lines in code blocks. You can specify line numbers to highlight after the language, as shown below:

```js {2,4-5}
import { Marp } from '@marp-team/marp-core';
import shiki from '@marp-team/marp-core/plugins/shiki';

const marp = new Marp().use(shiki());
const { html, css } = marp.render('# Hello, Marp!');
```

Color definitions

Previous syntax highlighting used .hljs-* classes, which made it difficult to customize styles in complex cases such as custom color-scheme classes and theme inheritance.

For making customization simple, v5 introduces a new approach that consolidates colors into about a dozen CSS variables. You also can use the light-dark() function to support both light and dark color schemes.

section {
  --marp-shiki-foreground: light-dark(#123c22, #7cff8a);
  --marp-shiki-background: light-dark(#eef8ef, #050a07);
  --marp-shiki-line-highlight: light-dark(#ccebd2, #123a24);
  --marp-shiki-token-constant: light-dark(#006e85, #5ee7ff);
  --marp-shiki-token-string: light-dark(#8a5a00, #ffe66d);
  --marp-shiki-token-comment: light-dark(#607866, #6f9b78);
  --marp-shiki-token-keyword: light-dark(#b01872, #ff6ac1);
  --marp-shiki-token-parameter: light-dark(#a24300, #ff9f43);
  --marp-shiki-token-function: light-dark(#0068a0, #67d8ff);
  --marp-shiki-token-string-expression: light-dark(#397800, #b8ff5a);
  --marp-shiki-token-punctuation: light-dark(#4f6955, #a8c7ad);
  --marp-shiki-token-link: light-dark(#005cc5, #58a6ff);
}

Please review .hljs-* classes in your style for syntax highlighting, and replace them with --marp-shiki-* CSS variable definitions.

See the documentation of color definitions for details.

A lightweight core by default for developers

Note

This section is for developers who use Marp Core as a library. If you are a user of Marp CLI (without engine customization) or Marp for VS Code, you can skip this section.

While adding highly requested features to Marp is welcome, the resulting bloat is a major concern for developers embedding Marp into their apps. Marpit framework solves this, but its bare-minimum features can be difficult for some.

Marp Core v5 makes the main @marp-team/marp-core package lightweight by separating 4 features, including Mermaid and Shiki, into core plugins with external dependencies. Developers can now choose only what they need for their apps.

• @marp-team/marp-core: A lightweight core with only essential features
• @marp-team/marp-core/plugins/shiki: Core plugin for syntax highlighting (Requires shiki)
• @marp-team/marp-core/plugins/mermaid: Core plugin for Mermaid rendering (Requires beautiful-mermaid)
• @marp-team/marp-core/plugins/katex: Core plugin for KaTeX math typesetting (Requires katex)
• @marp-team/marp-core/plugins/mathjax: Core plugin for MathJax math typesetting (Requires @mathjax/src and 4 font packages)

import { Marp } from '@marp-team/marp-core';
import katexPlugin from '@marp-team/marp-core/plugins/katex';
import shikiPlugin from '@marp-team/marp-core/plugins/shiki';

const marp = new Marp().use(shikiPlugin()).use(katexPlugin());

Check out README for details.

Comparison

Rough estimates for a minified browser ESM build before gzip. The full build includes all optional dependencies.

A lightweight core of v5 is 83.9% smaller than v4, and 95% smaller than v5 full.

Full build

Marp Core also provides a full build @marp-team/marp-core/full that includes all core plugins. It's useful for developers who want to migrate from v4.

import { Marp } from '@marp-team/marp-core/full';

If v5 becomes stable, the Marp ecosystem toolchain is going to use the full build, so there is no functional loss in Marp CLI and VS Code extension.

Prepare for v5

This is a guide for testing v5 features in Marp CLI. For future release of Marp ecosystem toolchain, Markdown authors and theme desingers can prepare for v5 full build.

1. Create a new Node.js (20.19+) project, and install Marp CLI v4.5.1 and Marp Core v5 (next tag).

   npm init
   npm install --save @marp-team/marp-cli@^4.5.1 @marp-team/marp-core@next
   

2. Install dependencies required by core plugins, by following https://github.com/marp-team/marp-core#core-plugins.

   npm install --save \
     shiki \
     beautiful-mermaid \
     katex \
     @mathjax/src \
     @mathjax/mathjax-bbm-font-extension \
     @mathjax/mathjax-bboldx-font-extension \
     @mathjax/mathjax-dsfont-font-extension \
     @mathjax/mathjax-mhchem-font-extension
   

3. Run Marp CLI.

   npx marp your-slides.md
   

   Marp CLI v4.5.1 and later automatically recognizes the installed Marp Core v5. If you are using an earlier CLI version, you have to specify --engine option: --engine @marp-team/marp-core/full

Helpful resources

• Migration guide to v5
• Theme authoring guide
• v5.0.0 release notes

For better stable release, please give the release candidate a try, and let me know your feedback! 📮

[yhatt]

For theme authors, I created the skill for AI coding agent to migrate your theme to support Marp Core v5. 🤖
👉 https://gist.github.com/yhatt/acea9267b5174a7dc3a112dd52966dcf

Download ZIP and extract to your skill directory, or run in your project:

npx skills add https://gist.github.com/acea9267b5174a7dc3a112dd52966dcf.git