gem-hunter

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's index.html.

Place Markdown named index.md or PITCHME.md (GitPitch style) to served directory. It would be redirected just accessing to http://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 are chrome, edge, and firefox. If set comma-separated browsers, Marp CLI will try to use the first available browser among them.

# Use Firefox for image conversion
marp --browser firefox ./slide.md -o slide.png

# Prefer to use Firefox first, then Chrome
marp --browser firefox,chrome ./slide.md -o slide.png

The default is a special value auto, which means to use the first available browser from chrome,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 path
marp --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 is bespoke.

marp --template bespoke slide-deck.md

The bespoke template is using Bespoke.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 gesture.
• Fullscreen: Toggle fullscreen by hitting f / F11 key.
• On-screen controller: There is a touch-friendly OSC. You may also disable by --bespoke.osc=false if unnecessary.
• Fragmented list: Recognize Marpit's fragmented list and appear list one-by-one if used * and 1) as the bullet marker.
• Presenter view: Open presenter view in external window by hitting p key. (It may become disabled when not fulfilled requirements for working)
• Overview view: Toggle overview view with o or Esc key in presentation and presenter views.
• 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 by View Transition API.

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

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

When the conversion engine is changed to Marpit framework by setting engine 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

Through global 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 supports additional global directives to specify metadata in Markdown. You can define meta values in Markdown front-matter.

---
title: Marp slide deck
description: An example slide deck created by Marp CLI
author: Yuki Hattori
keywords: marp,marp-cli,slide
url: 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 use Gaia 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 in Marpit's theme directive.

# Multiple theme CSS files
marp --theme-set theme-a.css theme-b.css theme-c.css -- deck-a.md deck-b.md

# Theme directory
marp --theme-set ./themes -- deck.md

Marp CLI is calling the Marpit framework based converter as "Engine". Normally we use the bundled Marp 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 framework
npm i @marp-team/marpit

# Specify engine to use Marpit
marp --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 representing the constructor option of Marpit/Marp Core.

The function must return a class that inherits from Marpit, or an instance of a Marpit-based engine created with the constructor options passed as an argument.

// engine.mjs
import { MarpitBasedEngine } from 'marpit-based-engine'

export default () => MarpitBasedEngine // Return a class inherited from Marpit

// or return an instance of Marpit-based engine
// export default (constructorOptions) => new MarpitBasedEngine(constructorOptions)

// engine.cjs (CommonJS)
const { MarpitBasedEngine } = require('marpit-based-engine')

module.exports = () => MarpitBasedEngine

// module.exports = function (constructorOptions) {
//   return new MarpitBasedEngine(constructorOptions)
// }

This function can return Promise object so you can use async function too.

export default async (constructorOptions) => {
  const { MarpitBasedEngine } = await import('marpit-based-engine')
  return new MarpitBasedEngine(constructorOptions)
}

Marp CLI also exposes marp 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.

import marpPlugin from 'marp-plugin-foo'
import andMorePlugin from 'marp-plugin-bar'

export default ({ marp }) => marp.use(marpPlugin).use(andMorePlugin)

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

import markdownItMark from 'markdown-it-mark'

export default ({ marp }) => marp.use(markdownItMark)

# Install markdown-it-mark into your project
npm i markdown-it-mark --save

# Specify the path to functional engine
marp --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 use an 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 or w/ 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 as marp.config.js, marp.config.mjs (ES Modules), marp.config.cjs (CommonJS), .marprc (JSON / YAML), and marp section of package.json.

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

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

# .marprc.yml
allowLocalFiles: true
options:
  looseYAML: false
  markdown:
    breaks: false
pdf: true

// marp.config.mjs
import markdownItContainer from 'markdown-it-container'

export default {
  // Customize engine on configuration file directly
  engine: ({ 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)

You can fine-tune constructor options for the engine, Marp Core / Marpit.

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

This configuration will set the constructor option for Marp Core as specified:

• Disables Marp Core's line breaks conversion (\n to <br />) to match for CommonMark, by passing markdown-it's breaks option as false.
• Disable minification for rendered theme CSS to make debug your style easily, by passing minifyCSS as false.

[!WARNING]

Some options may be overridden by used template.

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

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

export default config

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

import { defineConfig } from '@marp-team/marp-cli'

export default defineConfig({
  // ...
})

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

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

export default config

If you've installed both of Marp CLI and TypeScript (up to v6) into your local Node.js project, you can write a config by TypeScript: marp.config.ts. Marp CLI will try to transpile .ts with the project setting tsconfig.json.

If you're using the standalone binary, Marp CLI will try to load marp.config.ts by Node.js native TypeScript support. In this case, the project setting tsconfig.json will not be used, and there are some constraints.

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

// marp.config.ts
import { Marpit } from '@marp-team/marpit'
import { defineConfig } from '@marp-team/marp-cli'

export default defineConfig<typeof Marpit>({
  engine: Marpit,
  options: {
    // Suggest only Marpit constructor options
  },
})

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

import { marpCli } from '@marp-team/marp-cli'

try {
  const exitStatus = await marpCli(['test.md', '--pdf'])

  if (exitStatus > 0) {
    console.error(`Failure (Exit status: ${exitStatus})`)
  } else {
    console.log('Success')
  }
} catch (err) {
  console.error(err)
}

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

We have exported CLIError class and CLIErrorCode enum, to allow handling for specific errors that have already known by Marp CLI.

If CLIError instance was thrown, you can identify the reason why CLI threw error by checking errorCode member.

import { marpCli, CLIError } from '@marp-team/marp-cli'

try {
  await marpCli(['foobar.md', '--pdf'])
} catch (err) {
  if (err instanceof CLIError) {
    console.error(`Marp CLI Error (Error code: ${err.errorCode}):`, err)
  } else {
    console.error('Unexpected error:', err)
  }
}

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

waitForObservation() is helpful for handling them. It returns a Promise that resolves with a helper object when ready to observe resources in marpCli().

import { marpCli, waitForObservation } from '@marp-team/marp-cli'

// This call is not awaited so the server startup will continue in the background
marpCli(['--server', './slides/'])
  .then((exitCode) => console.log(`Done with exit code ${exitCode}`))
  .catch(console.error)

// Wait for the server to be ready
const { stop } = await waitForObservation()
console.log('Observed')

// ... Do something while observing resources ...

// Stop observing, and resolve the Promise from `marpCli()`
stop()

The resolved helper has stop() method for telling Marp CLI to stop observation and resolve the Promise from marpCli().

Are you interested in contributing? Please see CONTRIBUTING.md and the common contributing guideline for Marp team.

Managed by @marp-team.

• Yuki Hattori (@yhatt)

This tool releases under the MIT License.