marp-core: the converter behind Marp slides, and the v5 split into a core and plugins

A converter that sits on top of Marpit

marp-core is the core of the Marp converter, and the relationship to the framework underneath it is the first thing to understand. Marp Core extends the Marpit framework with practical Markdown syntax, advanced features, official themes and optional core plugins. Marpit is the underlying framework, and it is the layer that defines how a Markdown document is turned into a set of slides and how a theme is applied to them.

The practical API is small. Marp Core provides the `Marp` class, inherited from Marpit, so its basic usage is the same as Marpit's:

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

const marp = new Marp()
const { html, css } = marp.render('# Hello, marp-core!')

The render call returns the two things a slide tool needs: the HTML for the slides and the CSS that styles them. Everything else in the library is about the two halves of that contract, the Markdown dialect that becomes slides, and the theme system that decides what they look like.

The project is maintained by the Marp team, with Yuki Hattori credited as author, and it is published to npm as `@marp-team/marp-core` under the MIT licence. The package is TypeScript, built with `tsdown` per the `tsdown.config.ts` file, and tested with Jest through `jest.config.mjs`.

v5 split the package in two, and the size difference is stark

The most significant change in the recent history is structural. Since v5, Marp Core has been split into a lightweight core and optional core plugins, and the readme gives the bundled size for each entrypoint.

The main entrypoint, `@marp-team/marp-core`, is a lightweight core with Marp's essential features, at a rough estimate of 0.5MiB. The second entrypoint, `@marp-team/marp-core/full`, is a full build with all core plugins, which requires installing all the optional dependencies, at 11.4MiB. The readme notes that these are rough estimates for a minified browser ESM build before gzip, and that the full entrypoint includes all optional dependencies.

That is more than a twentyfold difference, and it is the reason for the split. The features that pull in Shiki, Mermaid, KaTeX or MathJax are large and are not needed by everyone, so a converter that only needs to lay out Markdown should not have to install a math typesetting engine to do it. The readme says the full build provides a consistent experience across the Marp toolchain, while for your own application it recommends the lightweight core with only the plugins you need.

There is a third entrypoint, `@marp-team/marp-core/browser`, and the readme points to the browser helper documentation for it. The exports map in the package manifest shows what it is for: a script build, `browser-iife.iife.js`, alongside the module and default builds, which is the shape a browser needs when it cannot use a module loader.

Plugins are added with use(), and each one drags in its own dependency

The optional core plugins are named after the technology they wrap. The `shiki` plugin provides syntax highlighting powered by Shiki and needs the `shiki` package. The `mermaid` plugin provides Mermaid rendering powered by beautiful-mermaid and needs that package. The `katex` plugin does math typesetting with KaTeX and needs `katex`. The `mathjax` plugin does math typesetting with MathJax and needs `@mathjax/src` plus four font extension packages, `mathjax-bbm-font-extension`, `mathjax-bboldx-font-extension`, `mathjax-dsfont-font-extension` and `mathjax-mhchem-font-extension`.

Using the full build means installing all of them:

npm install --save \
  @marp-team/marp-core@next \
  shiki \
  beautiful-mermaid \
  katex \
  @mathjax/src \
  @mathjax/mathjax-bbm-font-extension \
  @mathjax/mathjax-boldx-font-extension \
  @mathjax/mathjax-dsfont-font-extension \
  @mathjax/mathjax-mhchem-font-extension

But you do not have to take the full build. The plugins are added individually by chaining `use()`:

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())

And the readme notes that you can also add any Marpit-compatible plugin, which is the important detail: the plugin interface is Marpit's, not Marp Core's own, so a plugin written for Marpit works here too.

The internals are also visible in the manifest. The `imports` map resolves the plugin implementations conditionally, with a `node` condition pointing at a CommonJS build and a `default` condition pointing at an ES module build for each of KaTeX, MathJax, Mermaid and Shiki. That is the mechanism that lets the same package serve a Node application and a browser bundle, and it is why the plugin entrypoints ship in both formats.

Themes and Markdown syntax are where the real work is

The two features that make Marp a slide tool rather than a generic Markdown renderer are the dialect and the theme system, and both are documented in the repository.

The Markdown guide covers the syntax, including the practical extensions Marp adds on top of plain Markdown: page breaks, background images per slide, inline HTML, and the local directives that make a deck behave like a deck. The themes directory holds the official themes, and there is a separate theme authoring guide for writing a custom one that suits a brand.

That separation matters for an adopter. The converter is generic, and the look comes from a theme, which is a CSS layer you can write yourself. A team with an existing design system can express it as a theme rather than forking the converter, and a team that only needs text on a white background can skip the theme work entirely.

The configuration document covers integrating Marp Core into a project, and it is also where the browser helper is described. The package manifest shows the extent of the surface: type declarations for every entrypoint, separate builds for import and require, and per-plugin entrypoints under `./plugins/`, each with its own types.

For the file layout, the repository carries `src/`, `test/`, `themes/`, `docs/`, a `sandbox/` directory, `scripts/`, a `marp.config.mjs` for the project's own configuration, a `babel.config.js`, and an `eslint.config.mjs` with a `.stylelintrc.yml` for the theme CSS.

v5 is a release candidate, and the v4 line is still what the tools use

There is an important caveat at the top of the readme, and it changes how you should evaluate the project today. The note says that Marp Core v5 is currently a release candidate and that this readme documents v5, while current Marp tools may still use stable v4, with a `v4` branch available for the v4 documentation.

That is why the install instructions use the `next` tag rather than a plain version:

npm install --save @marp-team/marp-core@next

So the split described in this article, the lightweight core, the full build, the per-plugin entrypoints, exists in a release candidate rather than in a stable tag, and the published tooling in the Marp ecosystem may still be on v4. A team that needs to run the same converter as the rest of its toolchain has a reason to wait for the v5 stable release, and the v4 branch is the reference for the older API.

The migration document is the place to look for what actually changed. The readme lists it as one of five guides, and it is the first thing to read before upgrading an existing integration.

For requirements, Marp Core v5 supports Node.js 20.19 or later, and the readme strongly recommends using an actively supported Node.js version rather than the bare minimum.

Where marp-core is the wrong tool

Three boundaries are worth naming.

The first is that this is a library, not a command line tool. The repository description is the core of the Marp converter, and the usage section is JavaScript API usage. If you want a command that turns `slides.md` into a PDF, marp-core does not provide one: the usage section is JavaScript API usage only. Reaching for marp-core when you wanted a CLI means writing the wrapper yourself.

The second is the size and dependency trade, which is a trade rather than a free win. The lightweight core is small because the interesting features are optional, and every optional feature is a dependency you now have to keep updated. A team that wants the full build takes the 11.4MiB bundle and eight extra packages, including a MathJax install with four font extension packages. If your pipeline only ever renders plain text slides, taking Shiki and KaTeX along for the ride is a maintenance cost for nothing.

The third is the v5 status. Adopting a release candidate means your converter can change under you between patch versions, in a package that many other Marp tools depend on. The bundle sizes, the entrypoint names and the plugin loading are all new in v5, and the readme's own note that current Marp tools may still use stable v4 is a signal about how the ecosystem is moving.

The licence itself is not a consideration: MIT, released under that licence, with the file at the repository root. The maintenance record is healthy. v5.0.0 was published on 2026-08-07, v5.0.1 on 2026-08-09, v5.0.2 on 2026-09-04, with the last push to the repository on the same day, and the project keeps a `CHANGELOG.md`, CircleCI for the build and Codecov for coverage.

Editorial conclusion

marp-core fits a team embedding a slide converter into its own tool, a documentation pipeline that needs Markdown to become a deck, or a browser application that wants the converter without a CLI around it. It does not fit someone who wants a command line slide builder, because it exposes a JavaScript API rather than a command, and it is the wrong choice to depend on the v5 release candidate if you need the stability of the current v4 line. Before you upgrade, read the migration document in `docs/`, because the v5 split changed the entrypoints, and decide deliberately which plugins you want, since the full build is more than twenty times the size of the lightweight core.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. marp-team/marp-core on GitHub
4. README
5. Releases