Repository files navigation

A CLI interface, forMarp (using@marp-team/marp-core) and any slide deck converter based onMarpit framework.

It can convert Marp / Marpit Markdown files into static HTML / CSS, PDF, PowerPoint document, and image(s) easily.

npx (npm exec) is the best way to use the latest Marp CLI if you wantedone-shot Markdown conversionwithout install. Just run below if you haveinstalledNode.js v18 and later.

# Convert slide deck into HTMLnpx @marp-team/marp-cli@latest slide-deck.mdnpx @marp-team/marp-cli@latest slide-deck.md -o output.html# Convert slide deck into PDFnpx @marp-team/marp-cli@latest slide-deck.md --pdfnpx @marp-team/marp-cli@latest slide-deck.md -o output.pdf# Convert slide deck into PowerPoint document (PPTX)npx @marp-team/marp-cli@latest slide-deck.md --pptxnpx @marp-team/marp-cli@latest slide-deck.md -o output.pptx# Watch modenpx @marp-team/marp-cli@latest -w slide-deck.md# Server mode (Pass directory to serve)npx @marp-team/marp-cli@latest -s ./slides

Don't you like installing Node.js and Chrome to local? We have an official container image that is ready to use CLI.

⏩ Please refer how to use at Docker Hub.

docker pull marpteam/marp-cli

docker pull ghcr.io/marp-team/marp-cli

You can use the package manager to install and update Marp CLI easily.

Disclaimer: Package manifests are maintained by the community, not Marp team.

brew install marp-cli

scoop install marp

Node.js v18 and later is required to use Marp CLI.

We recommend to install Marp CLI into your Node.js project. You may control the CLI version (and engine if you want) exactly.

npm install --save-dev @marp-team/marp-cli

The installedmarp command is available innpm-scripts ornpx marp.

You can install with-g option if you want to usemarp command globally.

npm install -g @marp-team/marp-cli

We also provide standalone binaries for Linux, macOS (Apple Silicon), and Windows. These have bundled Marp CLI with Node.js binary, so no need to install Node.js separately.

⏩ Download the latest standalone binary from release page.

The passed markdown will be converted to HTML file by default. In the below example, a convertedslide-deck.html will output to the same directory.

marp slide-deck.md

You can change the output path by--output (-o) option.

marp slide-deck.md -o output.html

Marp CLI supports converting multiple files by passing multiple paths, directories, and glob patterns. In this case,--output option cannot use.

When you want to output the converted result to another directory with keeping the origin directory structure, you can use--input-dir (-I) option.--output option would be available for specify the output directory.

If you passed--pdf option or the output filename specified by--output (-o) option ends with.pdf, Marp CLI will try to convert Markdown into PDF file through the browser.

marp --pdf slide-deck.mdmarp slide-deck.md -o converted.pdf

• --pdf-notes: Add PDF note annotations to the lower left when the slide page hasMarpit presenter notes.
• --pdf-outlines: Add PDF outlines/bookmarks.

--pdf-outlines will make outlines based on slide pages and Markdown headings by default. If necessary, you may prevent making outlines from one of them, by setting--pdf-outlines.pages=false or--pdf-outlines.headings=false.

Do you want more familiar way to present and share your deck? PPTX conversion to create PowerPoint document is available by passing--pptx option or specify the output path with PPTX extension.

marp --pptx slide-deck.mdmarp slide-deck.md -o converted.pptx

A created PPTX includes rendered Marp slide pages and the support ofMarpit presenter notes. It can open with PowerPoint, Keynote, Google Slides, LibreOffice Impress, and so on...

A converted PPTX usually consists of pre-rendered background images, that is meaningcontents cannot to modify or re-use in PowerPoint. If you want to generate editable PPTX for modifying texts, shapes, and images in GUI, you can pass--pptx-editable option together with--pptx option.

marp --pptx --pptx-editable slide-deck.md

You can convert the slide deck into multiple images when specified--images [png|jpeg] option.

# Convert into multiple PNG image filesmarp --images png slide-deck.md# Convert into multiple JPEG image filesmarp --images jpeg slide-deck.md

Output files have a suffix of page number, likeslide-deck.001.png,slide-deck.002.png, and so on.

When you passed--image option or specified the output path with PNG/JPEG extension, Marp CLI will convertonly the first page (title slide) of the targeted slide deck into an image.

# Convert the title slide into an imagemarp --image png slide-deck.mdmarp slide-deck.md -o output.png

It would be useful for creatingOpen Graph image that can specify withimage global directive and--og-image option.

You can set the scale factor for rendered image(s) through--image-scale option. It is useful for making high-resolution image from the slide.

# Generate high-resolution image of the title slidemarp slide-deck.md -o title-slide@2x.png --image-scale 2

You can exportpresenter notes in Marp / Marpit Markdown as a text file by using--notes option or specifying the output path with TXT extension.

# Export presenter notes as a textmarp --notes slide-deck.mdmarp slide-deck.md -o output.txt

Because ofthe security reason,conversion that is using the browser cannot use local files by default.

Marp CLI would output incomplete result with warning if the blocked local file accessing is detected. We recommend uploading your assets to online.

If you really need to use local files in these conversion,--allow-local-files option helps to find your local files.Please use only to the trusted Markdown because there is a potential security risk.

marp --pdf --allow-local-files slide-deck.md

When converting multiple files, Marp CLI will process them in parallel with 5 concurrency by default. You can set the number of concurrency by--parallel (-P) option, or disable parallelism by--no-parallel.

Marp CLI will observe a change of Markdown and using theme CSS when passed with--watch (-w) option. The conversion will be triggered whenever the content of file is updated.

While you are opening the converted HTML in browser, it would refresh the opened page automatically.

Server mode supports on-demand conversion by HTTP request. We require to pass--server (-s) option and a directory to serve.

In this mode, the converted file outputs as the result of accessing to server, and not to disk.

You would get the converted PDF, PPTX, PNG, JPEG, and TXT by adding corresponded query string when requesting. e.g.http://localhost:8080/deck-a.md?pdf returns converted PDF.

Marp CLI server will provide the list of served files by default, but you can place the default Markdown deck like a common web server'sindex.html.

Place Markdown namedindex.md orPITCHME.md (GitPitch style) to served directory. It would be redirected just accessing tohttp://localhost:8080/.

When conversions were executed together with--preview (-p) option, Marp CLI will open preview window(s) to check the converted result immediately.

Unlike opening with browser, you may present deck with the immersive window.Watch mode is automatically enabled while using preview window.

You can specify the kind of browser for conversion by--browser option. Available browsers arechrome,edge, andfirefox. If set comma-separated browsers, Marp CLI will try to use the first available browser among them.

# Use Firefox for image conversionmarp --browser firefox ./slide.md -o slide.png# Prefer to use Firefox first, then Chromemarp --browser firefox,chrome ./slide.md -o slide.png

The default is a special valueauto, which means to use the first available browser fromchrome,edge,firefox.

If you have a browser binary that cannot find out by Marp CLI automatically, you can explicitly set the path to the browser executable through--browser-path option.

# Use Chromium-flavored browser (Chromium, Brave, Vivaldi, etc...)marp --browser-path /path/to/chromium-flavored-browser ./slide.md -o slide.pdf# Use Firefox with explicitly set pathmarp --browser firefox --browser-path /path/to/firefox ./slide.md -o slide.png

• --browser-protocol: Set the preferred protocol for connecting to the browser.
  • cdp:Chrome DevTools Protocol (default)
  • webdriver-bidi:WebDriver BiDi
• --browser-timeout: Set the timeout for each browser operation in seconds. (default:30 seconds)

You can choose a built-in HTML templates by--template option. Default template isbespoke.

marp --template bespoke slide-deck.md

Thebespoke template is usingBespoke.js as the name implies. It has several features to be useful in a real presentation. A few features may control by CLI options.

• Navigation: Navigate the deck through keyboard and swipe geasture.
• Fullscreen: Toggle fullscreen by hittingf /F11 key.
• On-screen controller: There is a touch-friendly OSC. You may also disable by--bespoke.osc=false if unnecessary.
• Fragmented list: RecognizeMarpit's fragmented list and appear list one-by-one if used* and1) as the bullet marker.
• Presenter view: Open presenter view in external window by hittingp key. (It may become disabled when not fulfilled requirements for working)
• Progress bar (optional): By setting--bespoke.progress option, you can add a progress bar on the top of the deck.
• Slide transitions: Support transitions (transition local directive) powered byView Transition API.

• Slide transitions inbespoke template
  Learn all about of slide transitions forbespoke template: Built-in transitions, custom transitions, and morphing animations.

Thebare template is a primitive template, and there is no extra features. It only has minimum assets to give your presentation with browser.

Whenthe conversion engine is changed to Marpit framework by settingengine option,it would not use any scripts. Even then, it has enough to use for the browser-based presentation.

marp --template bare --engine @marp-team/marpit slide-deck.md

Throughglobal directives or CLI options, you can set metadata for a converted HTML, PDF, and PPTX slide deck.

When a title was not defined, Marp CLI may assign the title from the first heading of Markdown automatically. If not wanted this detection, specify the title as empty string"".

Marp CLI supportsadditionalglobal directives to specify metadata in Markdown. You can define meta values in Markdown front-matter.

---title:Marp slide deckdescription:An example slide deck created by Marp CLIauthor:Yuki Hattorikeywords:marp,marp-cli,slideurl:https://marp.app/image:https://marp.app/og-image.jpg---#Marp slide deck

Marp CLI prefers CLI option to global directives. You can override metadata values by--title,--description,--author,--keywords,--url, and--og-image.

You can override theme you want to use by--theme option. For example to useGaia built-in theme in Marp Core:

marp --theme gaia

A custom theme created by user also can use easily by passing the path of CSS file.

marp --theme custom-theme.css

--theme-set option has to specify theme set composed by multiple theme CSS files. The registered themes are usable inMarpit'stheme directive.

# Multiple theme CSS filesmarp --theme-set theme-a.css theme-b.css theme-c.css -- deck-a.md deck-b.md# Theme directorymarp --theme-set ./themes -- deck.md

Marp CLI is calling theMarpit framework based converter as "Engine". Normally we use the bundledMarp Core, but you may swap the conversion engine to another Marpit based engine through--engine option.

You can use Marp (and compatible markdown-it) plugins while converting, or completely swap the converter to the other Marpit-based engine which published to npm.

For example, you can convert Markdown with using the pure Marpit framework.

# Install Marpit frameworknpm i @marp-team/marpit# Specify engine to use Marpitmarp --engine @marp-team/marpit marpit-deck.md

Notice that Marpit has not provided theme. It would be good to include inline style in Markdown, or pass CSS file by--theme option.

When you specified the path to JavaScript file (.js,.cjs, or.mjs) in--engine option, you may use more customized engine by a JavaScript function.

The functional engine should export a function as the default export, which should have a single argument representingthe constructor option of Marpit/Marp Core.

The function must return a class inherited from Marpit, or an instance of Marpit-based engine made by the parameter passed by argument.

// engine.mjs (ES modules)import{MarpitBasedEngine}from'marpit-based-engine'exportdefault()=>MarpitBasedEngine// Return a class inherited from Marpit

// engine.cjs (CommonJS)const{ MarpitBasedEngine}=require('marpit-based-engine')module.exports=function(constructorOptions){// Return an instance of Marpit initialized by passed constructor optionsreturnnewMarpitBasedEngine(constructorOptions)}

This function can returnPromise object so you can useasync function too.

exportdefaultasync(constructorOptions)=>{const{ MarpitBasedEngine}=awaitimport('marpit-based-engine')returnnewMarpitBasedEngine(constructorOptions)}

Marp CLI also exposesmarp getter property to the parameter. It returns a prepared instance of the built-in Marp Core engine, so you can apply several customizations to Marp engine with simple declarations.

constmarpPlugin=require('marp-plugin-foo')constandMorePlugin=require('marp-plugin-bar')module.exports=({ marp})=>marp.use(marpPlugin).use(andMorePlugin)

It allows converting Markdown with additional syntaxes that were provided by Marp (or compatible markdown-it) plugins.

// engine.mjsimportmarkdownItMarkfrom'markdown-it-mark'exportdefault({ marp})=>marp.use(markdownItMark)

# Install markdown-it-mark into your projectnpm i markdown-it-mark --save# Specify the path to functional enginemarp --engine ./engine.mjs slide-deck.md

The customized engine will convert==marked== to<mark>marked</mark>.

By using--version (-v) option, you may confirm the version of engine that is expected to use in current configuration.

$marp --version@marp-team/marp-cli v4.x.x (w/ @marp-team/marp-core v4.x.x)

Marp CLI prefers to usean installed core to local project by user than the bundled.

If the current project has installed@marp-team/marp-core individually, it would show its version and the annotation:w/ user-installed @marp-team/marp-core vX.X.X orw/ customized engine.

$npm i @marp-team/marp-cli @marp-team/marp-core@^4.0.0 --save-dev$npx marp --version@marp-team/marp-cli v4.x.x (w/ user-installed @marp-team/marp-core v4.0.0)

Marp CLI can be configured options with file, such asmarp.config.js,marp.config.mjs (ES Modules),marp.config.cjs (CommonJS),.marprc (JSON / YAML), andmarp section ofpackage.json.

It is useful to configure settings for the whole of project.

// package.json{"marp":{"inputDir":"./slides","output":"./public","themeSet":"./themes"}}

# .marprc.ymlallowLocalFiles:trueoptions:looseYAML:falsemarkdown:breaks:falsepdf:true

// marp.config.mjsimportmarkdownItContainerfrom'markdown-it-container'exportdefault{// Customize engine on configuration file directlyengine:({ marp})=>marp.use(markdownItContainer,'custom'),}

By default we use configuration file that is placed on current directory, but you may also specify the path for a configuration file by--config-file (--config /-c) option.

If you want to prevent looking up a configuration file, you can pass--no-config-file (--no-config) option.

Some of options that cannot specify through CLI options can be configured by file. (e.g.options field for the constructor option of used engine)

{"options": {"markdown": {"breaks":false    },"minifyCSS":false  }}

When Marp CLI has been installed into the local project, for getting the power of auto completion for the config, such asIntelliSense, you can annotate the config object through JSDoc, with Marp CLI'sConfig type.

/**@type {import('@marp-team/marp-cli').Config} */constconfig={// ...}exportdefaultconfig

Or you can import Vite-likedefineConfig helper from Marp CLI instead.

import{defineConfig}from'@marp-team/marp-cli'exportdefaultdefineConfig({// ...})

If you've swapped the engine into another Marpit based engine, you can provide better suggestion foroptions field by passing the engine type to generics.

/**@type {import('@marp-team/marp-cli').Config<typeof import('@marp-team/marpit').Marpit>} */constconfig={engine:'@marp-team/marpit',options:{// Suggest only Marpit constructor options, not Marp Core},}exportdefaultconfig

If you installedtypescript into your local project together with Marp CLI, you can write a config by TypeScriptmarp.config.ts. Marp CLI will try to transpile.ts with the project configurationtsconfig.json.

In TypeScript configuration, you can specify the custom engine as the generics fordefineConfig helper, like this:

// marp.config.tsimport{Marpit}from'@marp-team/marpit'import{defineConfig}from'@marp-team/marp-cli'exportdefaultdefineConfig<typeofMarpit>({engine:Marpit,options:{// Suggest only Marpit constructor options},})

You can use Marp CLI through Node.jsif installed Marp CLI into your local project.

const{ marpCli}=require('@marp-team/marp-cli')marpCli(['test.md','--pdf']).then((exitStatus)=>{if(exitStatus>0){console.error(`Failure (Exit status:${exitStatus})`)}else{console.log('Success')}}).catch(console.error)

marpCli() accepts an argument of CLI options as array, and returnsPromise to resolve an expected exit status in CLI. It would be rejected with the instance ofError if CLI met an error to suspend the conversion process.

We have exportedCLIError class andCLIErrorCode enum from@marp-team/marp-cli, to allow handling for specific errors that have already known by Marp CLI.

IfCLIError instance was thrown, you can identify the reason why CLI threw error by checkingerrorCode member.

marpCli() would not be resolved initiatively if started some observation: Watch mode, server mode, and preview window.

waitForObservation() is helpful to handle them. It returnsPromise that would be resolved with helper object when ready to observe resources inmarpCli().

const{ marpCli, waitForObservation}=require('@marp-team/marp-cli')marpCli(['--server','./slides/']).then((exitCode)=>console.log(`Done with exit code${exitCode}`)).catch(console.error)waitForObservation().then(({ stop})=>{console.log('Observed')// Stop observations to resolve marpCli()'s Promisestop()})

The resolved helper hasstop() method for telling Marp CLI to stop observation and resolvePromise.

Are you interested in contributing? Please seeCONTRIBUTING.md andthe common contributing guideline for Marp team.

Managed by@marp-team.

• Yuki Hattori (@yhatt)

This tool releases under theMIT License.