Marp: The Markdown Presentation Ecosystem for Engineers and Writers

What Marp solves for presentation authors

Presentation tools like PowerPoint and Google Slides require manual layout work: dragging text boxes, aligning elements, applying themes by clicking through menus. For engineers and technical writers who already work in Markdown, this is friction. Marp removes that friction by treating a presentation as a text file with directives.

The core model is simple: a Markdown file where horizontal rules (---) separate slides. A Marp-aware renderer reads the file and produces a slide deck. The author writes prose and code in a text editor, applies a theme by name in a front matter block, and converts to the target format. The layout is handled by the theme, not by manual positioning.

Marp is specifically designed for slide content that is primarily text, code, and images. Technical talks, documentation walkthroughs, architecture reviews, and onboarding presentations are good fits. Visual presentations with complex layouts, custom animations, or interactive charts require either substantial CSS customization or a different tool.

The README describes the project as 'the ecosystem to write your presentation with plain Markdown', which captures the scope accurately. The ecosystem approach means that Marp's functionality is spread across several repositories, each with a focused scope, rather than in a single monolithic application.

The Marp ecosystem: Marpit, Marp Core, Marp CLI, and Marp for VS Code

The Marp ecosystem has a layered architecture. At the base is Marpit, described in the README as 'the skinny framework for creating slide deck from Markdown'. Marpit handles the fundamental task of parsing Marp Markdown and producing slide structures with theme support. Its documentation is at marpit.marp.app.

Marp Core builds on Marpit and adds practical features: built-in themes, additional Markdown extensions, and a broader set of slide directives. Marp Core is the layer that most users interact with indirectly, because the CLI and VS Code extension both use it.

Marp CLI, available as @marp-team/marp-cli on npm, is the command-line conversion tool. It converts Marp Markdown files to HTML, PDF, PPTX, and image formats. This is the tool for batch conversion, CI/CD integration, and generating final output files outside of the editor.

Marp for VS Code is a VS Code extension that provides live preview of Marp slides inside the editor as the author types. It is available through the VS Code Marketplace as marp-team.marp-vscode. For many users, this extension is the primary interface to Marp: write in the editor, preview instantly, then export when ready.

The entrance repository at marp-team/marp does not itself contain the Marp source code. Its role is to serve as the public entry point, hold the project website in the /website directory, and link the ecosystem components together in its README. The actual Marp code lives in the sub-repositories.

The Marp slide format and theme system

A Marp presentation is a Markdown file with a small number of conventions. The most important is that a line containing only --- creates a new slide. Front matter at the top of the file, formatted as YAML between --- markers, sets document-level directives like the theme name and pagination settings.

Marp Core ships with built-in themes that control the visual design: font choices, color schemes, code block formatting, and layout proportions. The theme source is in the marp-core repository at github.com/marp-team/marp-core/tree/main/themes. Users can write custom themes in CSS following the Marpit theme specification.

Code blocks in Marp presentations render with syntax highlighting, which is a primary reason engineers use Marp for technical talks. Images can be positioned using Marp's image syntax directives, which extend standard Markdown image syntax with size and positioning parameters.

The format is plain text and version-controllable, which is a practical advantage for teams that manage documentation in git repositories. A presentation stored as a Markdown file can be reviewed in pull requests, diffed like any text file, and exported to the final format as part of a CI/CD pipeline using Marp CLI.

Converting slides: what Marp CLI produces

Marp CLI is the conversion engine. It reads a Marp Markdown file and converts it to HTML (a self-contained web page), PDF, PPTX (PowerPoint format), or images. The README and npm package for Marp CLI are at @marp-team/marp-cli.

HTML output produces a self-contained slide deck that can be opened in a browser, hosted on a web server, or embedded in documentation sites. The slide controls work in the browser. PDF output is suitable for sending to audiences who need a static file. PPTX output allows further editing in PowerPoint or presentation platforms that accept PPTX import.

The conversion from Marp Markdown to PPTX happens through Marp Core's rendering pipeline, which means the visual design from the CSS theme carries through into the PPTX structure. Complex CSS layouts may not translate perfectly to PPTX, since PPTX has its own layout model.

Batch conversion, watch mode for development, and server mode for live preview are all features documented in the Marp CLI repository. CI/CD integration is a documented use case: generating a PDF from a Markdown presentation in a GitHub Actions workflow is a common pattern for teams that store presentations in version control.

Marp versus Slidev: the key difference in approach

Slidev is a Vue-based presentation framework that runs as a Node.js development server and produces interactive slides with Vue component support, live code execution, and animations. The author writes Markdown with embedded Vue syntax, and the output is a running web application.

Marp's model is different. Marp converts Markdown to static output formats: HTML, PDF, PPTX, and images. There is no runtime, no embedded framework, and no live code execution in the output. A Marp presentation is a file, not a running application.

The practical implication: Marp presentations are simpler to distribute and more predictable in output format, while Slidev presentations have more interactive capability but require a Node.js environment to develop and a web server or specific hosting to share in their native interactive form.

For a talk that consists of text, code snippets, and images with no runtime interactivity required, Marp's static conversion model has less operational overhead. For a demo-heavy presentation where the author wants to run live code or embed interactive components, Slidev's Vue model provides capabilities that Marp does not.

The README for marp-team/marp links to an awesome-marp list at github.com/marp-team/awesome-marp, which documents community-built themes, tools, and integrations for the ecosystem.

Where Marp does not fit: real limitations

Marp's strength is its simplicity, and that simplicity comes with firm limits. Slide layouts in Marp are controlled by CSS themes, which means complex custom layouts require CSS knowledge. There is no visual drag-and-drop layout editor.

Animations beyond what CSS transitions provide are not supported. A talk that requires animated diagrams, motion graphics, or step-by-step reveals synchronized to speech will need either a different tool or substantial CSS customization.

Marp does not execute code. A Marp code block is a formatted text display, not a running environment. For live coding demonstrations, the presenter must switch to a separate terminal or editor.

The project's older Marp Web interface (marp-web, built on PWA and Preact) is listed as outdated/inactive in the current README. The React and Vue renderer components (marp-react, marp-vue) are also listed as outdated. The active parts of the ecosystem are Marpit, Marp Core, Marp CLI, and the VS Code extension.

The entrance repository at marp-team/marp had its last push on 2026-07-29. The sub-repositories that contain the actual code are independently maintained and may have more recent activity.

Licensing, maintenance, and how the project is organized

All Marp components are MIT licensed. The organization is marp-team on GitHub, and the README credits Yuki Hattori as the primary author. The project accepts sponsorships and lists organizational and personal sponsors in the README.

The CONTRIBUTING.md file, referenced in the README, lives in the marp-team/.github repository at github.com/marp-team/.github/blob/master/CONTRIBUTING.md. Issues and discussions should be filed in the relevant sub-repository rather than in the entrance repository, since the entrance repository's scope is the project website and ecosystem overview.

The README notes an older classic Marp application at github.com/yhatt/marp, which is a previous generation of the project and is now a 'gravesite'. New users should use the current ecosystem, not the classic application.

The discussion forum for the Marp project is at github.com/marp-team/marp/discussions. The awesome-marp list at github.com/marp-team/awesome-marp documents community extensions, themes, and tooling that extend the core ecosystem.

Editorial conclusion

Marp is the right choice for engineers and technical writers who want to author presentations in plain text and convert them to PDF or PPTX for distribution, without leaving a code editor. The VS Code extension makes iteration fast. The main limitation is that Marp's output is static: it does not support interactive slides, embedded live code execution, or animations beyond CSS-based transitions. Teams who need interactive features in their presentations should evaluate Slidev instead. To start with Marp, install the Marp for VS Code extension from the VS Code Marketplace or use Marp CLI via npm from the @marp-team/marp-cli package.

Frequently asked questions

Official sources

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