========================
CODE SNIPPETS
========================
TITLE: Marp CLI File-Based Configuration Example
DESCRIPTION: Example JSON configuration for Marp CLI, demonstrating how to customize engine constructor options like disabling line breaks conversion in Markdown and preventing minification of rendered theme CSS for easier debugging.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_39

LANGUAGE: JSON
CODE:
```
{
  "options": {
    "markdown": {
      "breaks": false
    },
    "minifyCSS": false
  }
}
```

----------------------------------------

TITLE: Install Marp CLI via Package Managers
DESCRIPTION: Instructions for installing Marp CLI using Homebrew on macOS and Scoop on Windows. These methods leverage community-maintained package manifests for easy installation and updates.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_2

LANGUAGE: bash
CODE:
```
brew install marp-cli
```

LANGUAGE: cmd
CODE:
```
scoop install marp
```

----------------------------------------

TITLE: Install and Verify Marp Core Version
DESCRIPTION: This snippet demonstrates how to install a specific version of `@marp-team/marp-core` as a development dependency alongside `@marp-team/marp-cli` and then verify that Marp CLI is using the user-installed core version.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_34

LANGUAGE: console
CODE:
```
$ npm i @marp-team/marp-cli @marp-team/marp-core@^4.0.0 --save-dev
$ npx marp --version
```

----------------------------------------

TITLE: Install Marp CLI Locally with npm
DESCRIPTION: Guide to installing Marp CLI as a development dependency within a Node.js project. This allows precise version control and usage via npm-scripts or `npx marp`, requiring Node.js v18+.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_3

LANGUAGE: bash
CODE:
```
npm install --save-dev @marp-team/marp-cli
```

----------------------------------------

TITLE: Install Marp CLI Globally with npm
DESCRIPTION: Instructions for a global installation of Marp CLI using npm. This makes the `marp` command available system-wide, requiring Node.js v18+.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_4

LANGUAGE: bash
CODE:
```
npm install -g @marp-team/marp-cli
```

----------------------------------------

TITLE: Marp CLI defineConfig Helper for Configuration
DESCRIPTION: JavaScript example demonstrating the use of Marp CLI's `defineConfig` helper function. This utility provides type-safe configuration with auto-completion, similar to patterns found in build tools like Vite.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_41

LANGUAGE: JavaScript
CODE:
```
import { defineConfig } from '@marp-team/marp-cli'

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

----------------------------------------

TITLE: Convert with Bare Template and Marpit Engine in Marp CLI
DESCRIPTION: This example shows how to convert a slide deck using the minimalist 'bare' template while explicitly setting the conversion engine to @marp-team/marpit. This configuration results in a presentation that does not rely on JavaScript.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_21

LANGUAGE: bash
CODE:
```
marp --template bare --engine @marp-team/marpit slide-deck.md
```

----------------------------------------

TITLE: Marp CLI JSDoc Type Annotation for Configuration
DESCRIPTION: JavaScript example showing how to use JSDoc with Marp CLI's `Config` type. This annotation provides IntelliSense and auto-completion for configuration objects in editors like VS Code when Marp CLI is installed locally.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_40

LANGUAGE: JavaScript
CODE:
```
/** @type {import('@marp-team/marp-cli').Config} */
const config = {
  // ...
}

export default config
```

----------------------------------------

TITLE: Configure Marp CLI in package.json
DESCRIPTION: This example shows how to define Marp CLI options within the `marp` section of your `package.json` file. This method is useful for configuring project-wide settings such as input directory for slides, output directory for generated files, and the location of custom themes.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_35

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

----------------------------------------

TITLE: Convert Marp Markdown with npx
DESCRIPTION: Use `npx` to convert Marp Markdown files into HTML, PDF, or PPTX, or to run in watch/server mode. This method allows one-shot conversions without a global installation, requiring Node.js v18+ and a browser.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_0

LANGUAGE: bash
CODE:
```
npx @marp-team/marp-cli@latest slide-deck.md
npx @marp-team/marp-cli@latest slide-deck.md -o output.html

npx @marp-team/marp-cli@latest slide-deck.md --pdf
npx @marp-team/marp-cli@latest slide-deck.md -o output.pdf

npx @marp-team/marp-cli@latest slide-deck.md --pptx
npx @marp-team/marp-cli@latest slide-deck.md -o output.pptx

npx @marp-team/marp-cli@latest -w slide-deck.md

npx @marp-team/marp-cli@latest -s ./slides
```

----------------------------------------

TITLE: Use Marpit Framework as Conversion Engine in Marp CLI
DESCRIPTION: Shows how to install the `@marp-team/marpit` framework and specify it as the conversion engine for Marp CLI using the `--engine` option. Note that Marpit itself does not provide themes, requiring inline styles or external CSS.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_27

LANGUAGE: bash
CODE:
```
# Install Marpit framework
npm i @marp-team/marpit
```

LANGUAGE: bash
CODE:
```
# Specify engine to use Marpit
marp --engine @marp-team/marpit marpit-deck.md
```

----------------------------------------

TITLE: Integrate markdown-it-mark Plugin with Marp CLI Functional Engine
DESCRIPTION: Provides a practical example of integrating the `markdown-it-mark` plugin using a functional engine. This enables the `==marked==` syntax in Markdown, which converts to `<mark>marked</mark>` in the output.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_32

LANGUAGE: javascript
CODE:
```
// engine.mjs
import markdownItMark from 'markdown-it-mark'

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

LANGUAGE: bash
CODE:
```
# Install markdown-it-mark into your project
npm i markdown-it-mark --save
```

LANGUAGE: bash
CODE:
```
# Specify the path to functional engine
marp --engine ./engine.mjs slide-deck.md
```

----------------------------------------

TITLE: Override Marp CLI Output Theme
DESCRIPTION: This example demonstrates how to change the default visual theme for a Marp CLI conversion. By using the --theme option, users can specify a built-in theme like 'gaia' to customize the appearance of their generated presentation.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_24

LANGUAGE: bash
CODE:
```
marp --theme gaia
```

----------------------------------------

TITLE: Customize Marp Engine with ES Module Config
DESCRIPTION: This example demonstrates how to customize the Marp engine directly within an ES Module configuration file (`marp.config.mjs`). It shows importing a `markdown-it-container` plugin and applying it to the Marp instance, allowing for advanced engine modifications.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_37

LANGUAGE: javascript
CODE:
```
// marp.config.mjs
import markdownItContainer from 'markdown-it-container'

export default {
  // Customize engine on configuration file directly
  engine: ({ marp }) => marp.use(markdownItContainer, 'custom'),
}
```

----------------------------------------

TITLE: Define Functional Engine (CommonJS) for Marp CLI
DESCRIPTION: Provides an example of a CommonJS functional engine that exports a function. This function receives constructor options and should return an instance of a Marpit-based engine initialized with those options.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_29

LANGUAGE: javascript
CODE:
```
// engine.cjs (CommonJS)
const { MarpitBasedEngine } = require('marpit-based-engine')

module.exports = function (constructorOptions) {
  // Return an instance of Marpit initialized by passed constructor options
  return new MarpitBasedEngine(constructorOptions)
}
```

----------------------------------------

TITLE: Marp CLI: Generate Editable PowerPoint (PPTX) - Experimental
DESCRIPTION: This experimental snippet shows how to generate an editable PowerPoint document from a Markdown slide deck. It requires both the `--pptx` and `--pptx-editable` options, and also necessitates the installation of LibreOffice Impress. Note that this option may result in lower slide reproducibility and does not support presenter notes.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_9

LANGUAGE: bash
CODE:
```
marp --pptx --pptx-editable slide-deck.md
```

----------------------------------------

TITLE: Define Functional Engine (ES Modules) for Marp CLI
DESCRIPTION: Provides an example of an ES module functional engine that exports a class inherited from Marpit as the default export. This allows for highly customized conversion logic.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_28

LANGUAGE: javascript
CODE:
```
// engine.mjs (ES modules)
import { MarpitBasedEngine } from 'marpit-based-engine'

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

----------------------------------------

TITLE: Configure Marp CLI server port
DESCRIPTION: When running Marp CLI in server mode, you can set the listening port by defining the `PORT` environment variable before executing the command. This example sets the server to listen on port 5000.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_15

LANGUAGE: bash
CODE:
```
PORT=5000 marp -s ./slides
```

----------------------------------------

TITLE: Enable HTML Attributes for Morphing in Marp CLI
DESCRIPTION: This snippet shows the command-line option required to enable rendering of raw HTML `data-*` attributes in Marp CLI, which is necessary for the `data-morph` based morphing animation example to function correctly due to security reasons.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_13

LANGUAGE: Bash
CODE:
```
marp morphable.md --html
```

----------------------------------------

TITLE: Pull Marp CLI Container Image
DESCRIPTION: Commands to pull the official Marp CLI container image from Docker Hub and GitHub Container Registry. This provides a self-contained environment, eliminating the need for local Node.js or browser installations.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_1

LANGUAGE: bash
CODE:
```
docker pull marpteam/marp-cli
```

LANGUAGE: bash
CODE:
```
docker pull ghcr.io/marp-team/marp-cli
```

----------------------------------------

TITLE: Set explicit browser executable path for Marp CLI
DESCRIPTION: If Marp CLI cannot automatically locate your browser binary, use the `--browser-path` option to explicitly provide the path to the executable. This is useful for custom browser installations or Chromium-flavored browsers.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_17

LANGUAGE: bash
CODE:
```
# 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
```

----------------------------------------

TITLE: Animate Layer Order with z-index for Marp Transitions in CSS
DESCRIPTION: This example demonstrates how to animate the `z-index` property to dynamically swap the order of layers during a Marp transition, enabling more complex visual effects. It shows a `swap` transition where the incoming slide moves from back to front at 50% of the animation duration, while both slides also translate horizontally.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_10

LANGUAGE: CSS
CODE:
```
/** Declare `swap` transition */
@keyframes marp-incoming-transition-swap {
  /* Incoming slide will swap from back to front at 50% of animation */
  from {
    z-index: -1;
  }
  to {
    z-index: 0;
  }

  /* Declarations for moving animation */
  0% {
    transform: translateX(0);
  }
  50% {
    transform: translateX(50%);
  }
  100% {
    transform: translateX(0);
  }
}

@keyframes marp-outgoing-transition-swap {
  0% {
    transform: translateX(0);
  }
  50% {
    transform: translateX(-50%);
  }
  100% {
    transform: translateX(0);
  }
}
```

----------------------------------------

TITLE: Prevent Backward Transition Fallback with Empty Keyframes in CSS
DESCRIPTION: This example illustrates how to prevent Marp CLI from falling back to normal keyframes during backward navigation when a specific backward animation is not desired. It achieves this by declaring an empty `@keyframes` block for the backward animation, demonstrated with a `zoom-out` transition.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_7

LANGUAGE: CSS
CODE:
```
/* Define `zoom-out` transition */
@keyframes marp-outgoing-transition-zoom-out {
  from {
    transform: scale(1);
  }
  to {
    transform: scale(0);
  }
}
@keyframes marp-incoming-transition-zoom-out {
  /* Send the layer for new slide to back (See also "Layer order") */
  from,
  to {
    z-index: -1;
  }
}

@keyframes marp-outgoing-transition-backward-zoom-out {
  /****** Declare empty keyframes to disable fallback ******/
}
@keyframes marp-incoming-transition-backward-zoom-out {
  from {
    transform: scale(0);
  }
  to {
    transform: scale(1);
  }
}
```

----------------------------------------

TITLE: Mark Morphable Content Using HTML data-morph Attribute in Marp
DESCRIPTION: This example illustrates how to define morphable elements using custom HTML `data-morph` attributes within Marp Markdown. It leverages the advanced `attr()` CSS function to dynamically set `view-transition-name` based on the `data-morph` attribute, allowing for flexible morphing of elements like text bars. It notes the requirement for Chrome 133+ and the need for the `--html` CLI option.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_12

LANGUAGE: Markdown
CODE:
```
---
header: Bubble sort
transition: fade
style: |
  /* Define the style of morphable elements (Requires Chrome 133 and later) */
  [data-morph] {
    view-transition-name: attr(data-morph type(<custom-ident>), none);
  }

  /* Global style */
  section {
    font-size: 60px;
  }
---

<span data-morph="bar7">███████</span> 7
<span data-morph="bar5">█████</span> 5
<span data-morph="bar3">███</span> 3
<span data-morph="bar9">█████████</span> 9

---

<span data-morph="bar5">█████</span> 5
<span data-morph="bar7">███████</span> 7
<span data-morph="bar3">███</span> 3
<span data-morph="bar9">█████████</span> 9

---

<span data-morph="bar5">█████</span> 5
<span data-morph="bar3">███</span> 3
<span data-morph="bar7">███████</span> 7
<span data-morph="bar9">█████████</span> 9

---

<span data-morph="bar3">███</span> 3
<span data-morph="bar5">█████</span> 5
<span data-morph="bar7">███████</span> 7
<span data-morph="bar9">█████████</span> 9
```

----------------------------------------

TITLE: Marp CLI Configuration Options Reference
DESCRIPTION: This section provides a detailed reference for all configurable options in Marp CLI, outlining their data types, associated command-line arguments, and a clear explanation of their functionality and usage.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_47

LANGUAGE: APIDOC
CODE:
```
Option: allowLocalFiles
  Type: boolean
  CLI Option: --allow-local-files
  Description: Allow to access local files from Markdown while converting PDF (NOT SECURE)

Option: author
  Type: string
  CLI Option: --author
  Description: Define author of the slide deck

Option: bespoke
  Type: object
  Description: Setting options for bespoke template
  Properties:
    osc:
      Type: boolean
      CLI Option: --bespoke.osc
      Description: [Bespoke] Use on-screen controller (true by default)
    progress:
      Type: boolean
      CLI Option: --bespoke.progress
      Description: [Bespoke] Use progress bar (false by default)
    transition:
      Type: boolean
      CLI Option: --bespoke.transition
      Description: [Bespoke] Use [transitions] (Only in browsers supported [View Transition API]: true by default)

Option: browser
  Type: string | string[]
  CLI Option: --browser
  Description: The kind of browser for conversion (auto by default)

Option: browserPath
  Type: string
  CLI Option: --browser-path
  Description: Path to the browser executable

Option: browserProtocol
  Type: cdp | webdriver-bidi
  CLI Option: --browser-protocol
  Description: Set the preferred protocol for connecting to the browser (cdp by default)

Option: browserTimeout
  Type: number
  CLI Option: --browser-timeout
  Description: Set the timeout for each browser operation in seconds (30 by default)

Option: description
  Type: string
  CLI Option: --description
  Description: Define description of the slide deck

Option: engine
  Type: string | Class | Function
  CLI Option: --engine
  Description: Specify Marpit based engine

Option: html
  Type: boolean | object
  CLI Option: --html
  Description: Enable or disable HTML tags (Configuration file can pass [the whitelist object] if you are using Marp Core)

Option: image
  Type: png | jpeg
  CLI Option: --image
  Description: Convert the first slide page into an image file

Option: images
  Type: png | jpeg
  CLI Option: --images
  Description: Convert slide deck into multiple image files

Option: imageScale
  Type: number
  CLI Option: --image-scale
  Description: The scale factor for rendered images (1 by default, or 2 for PPTX conversion)

Option: inputDir
  Type: string
  CLI Option: --input-dir -I
  Description: The base directory to find markdown and theme CSS

Option: jpegQuality
  Type: number
  CLI Option: --jpeg-quality
  Description: Setting JPEG image quality (85 by default)

Option: keywords
  Type: string | string[]
  CLI Option: --keywords
  Description: Define keywords for the slide deck (Accepts comma-separated string and array of string)

Option: lang
  Type: string
  CLI Option: (None)
  Description: Define the language of converted HTML

Option: notes
  Type: boolean
  CLI Option: --notes
  Description: Convert slide deck notes into a text file

Option: ogImage
  Type: string
  CLI Option: --og-image
  Description: Define [Open Graph] image URL

Option: options
  Type: object
  CLI Option: (None)
  Description: The base options for the constructor of engine

Option: output
  Type: string
  CLI Option: --output -o
  Description: Output file path (or directory when input-dir is passed)
```

----------------------------------------

TITLE: Marp CLI Bespoke Template Features Overview
DESCRIPTION: This documentation outlines the various interactive and presentation features provided by the 'bespoke' HTML template. Features include navigation, fullscreen toggle, an on-screen controller, fragmented list support, presenter view, and optional progress bar.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_20

LANGUAGE: APIDOC
CODE:
```
Navigation: Navigate the deck through keyboard and swipe geasture.
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)
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.
```

----------------------------------------

TITLE: Check Marp CLI and Engine Version
DESCRIPTION: Explains how to use the `--version` or `-v` option to confirm the versions of both Marp CLI and the currently configured conversion engine.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_33

LANGUAGE: console
CODE:
```
$ marp --version
@marp-team/marp-cli v4.x.x (w/ @marp-team/marp-core v4.x.x)
```

----------------------------------------

TITLE: Marp CLI Metadata Configuration via CLI Options
DESCRIPTION: This table details the command-line options available in Marp CLI for defining metadata. These options allow users to set properties like title, description, author, keywords, URL, and Open Graph image for the generated HTML, PDF, and PPTX outputs.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_22

LANGUAGE: APIDOC
CODE:
```
| Global directives | CLI option | Description | Available in |
| :-----------------: | :-------------: | :------------------------------ | :-------------- |
|       `title`       |    `--title`    | Define title of the slide deck  | HTML, PDF, PPTX |
|    `description`    | `--description` | Define description of the slide | HTML, PDF, PPTX |
|      `author`       |   `--author`    | Define author of the slide deck | HTML, PDF, PPTX |
|     `keywords`      |  `--keywords`   | Define comma-separated keywords | HTML, PDF       |
|        `url`        |     `--url`     | Define [canonical URL]          | HTML            |
|       `image`       |  `--og-image`   | Define [Open Graph] image URL   | HTML            |
```

----------------------------------------

TITLE: Use Custom Theme with Marp CLI
DESCRIPTION: Explains how to apply a single custom CSS theme file to Marp CLI presentations by passing its path to the `--theme` option.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_25

LANGUAGE: bash
CODE:
```
marp --theme custom-theme.css
```

----------------------------------------

TITLE: Marp CLI: Convert Markdown to PowerPoint (PPTX)
DESCRIPTION: This snippet demonstrates how to convert a Markdown slide deck into a PowerPoint document (PPTX). This conversion is enabled by passing the `--pptx` option or by specifying the output path with a `.pptx` extension.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_8

LANGUAGE: bash
CODE:
```
marp --pptx slide-deck.md
marp slide-deck.md -o converted.pptx
```

----------------------------------------

TITLE: Marp CLI: Convert Markdown to PDF
DESCRIPTION: This snippet illustrates how to convert a Markdown slide deck into a PDF file. This can be achieved either by using the `--pdf` option or by specifying an output filename with a `.pdf` extension. Additional options like `--pdf-notes` for presenter notes and `--pdf-outlines` for PDF bookmarks (which can be configured for pages or headings) are also available.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_7

LANGUAGE: bash
CODE:
```
marp --pdf slide-deck.md
marp slide-deck.md -o converted.pdf
```

----------------------------------------

TITLE: Use Built-in HTML Templates with Marp CLI
DESCRIPTION: This snippet demonstrates how to specify a built-in HTML template, such as 'bespoke', for a slide deck. The --template CLI option is used to apply the desired presentation style.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_19

LANGUAGE: bash
CODE:
```
marp --template bespoke slide-deck.md
```

----------------------------------------

TITLE: Marp CLI Command Line Options Reference
DESCRIPTION: Detailed reference for command-line interface options available in Marp CLI, including their types, associated CLI flags, and a brief description of their functionality. Nested options are indicated by indentation.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_38

LANGUAGE: APIDOC
CODE:
```
Option: parallel
  Type: boolean | number
  CLI Flag: --parallel -P
  Description: Set the number of concurrency for parallel conversion (5 by default)

Option: pdf
  Type: boolean
  CLI Flag: --pdf
  Description: Convert slide deck into PDF

Option: pdfNotes
  Type: boolean
  CLI Flag: --pdf-notes
  Description: Add presenter notes to PDF as annotations

Option: pdfOutlines
  Type: boolean | object
  CLI Flag: --pdf-outlines
  Description: Add outlines (bookmarks) to PDF
  Properties:
    Option: pages
      Type: boolean
      CLI Flag: --pdf-outlines.pages
      Description: Make PDF outlines from slide pages (true by default when pdfOutlines is enabled)
    Option: headings
      Type: boolean
      CLI Flag: --pdf-outlines.headings
      Description: Make PDF outlines from Markdown headings (true by default when pdfOutlines is enabled)

Option: pptx
  Type: boolean
  CLI Flag: --pptx
  Description: Convert slide deck into PowerPoint document

Option: pptxEditable
  Type: boolean
  CLI Flag: --pptx-editable
  Description: [EXPERIMENTAL] Generate editable PPTX when converting to PPTX

Option: preview
  Type: boolean
  CLI Flag: --preview -p
  Description: Open preview window

Option: server
  Type: boolean
  CLI Flag: --server -s
  Description: Enable server mode

Option: template
  Type: bare | bespoke
  CLI Flag: --template
  Description: Choose template (bespoke by default)

Option: theme
  Type: string
  CLI Flag: --theme
  Description: Override theme by name or CSS file

Option: themeSet
  Type: string | string[]
  CLI Flag: --theme-set
  Description: Path to additional theme CSS files

Option: title
  Type: string
  CLI Flag: --title
  Description: Define title of the slide deck

Option: url
  Type: string
  CLI Flag: --url
  Description: Define canonical URL

Option: watch
  Type: boolean
  CLI Flag: --watch -w
  Description: Watch input markdowns for changes
```

----------------------------------------

TITLE: Programmatic Marp CLI Usage with marpCli() Function
DESCRIPTION: Shows how to use the `marpCli()` function from the `@marp-team/marp-cli` package to programmatically execute Marp CLI commands. It accepts CLI options as an array and returns a Promise that resolves with the exit status or rejects with an `Error`.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_44

LANGUAGE: javascript
CODE:
```
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)
```

----------------------------------------

TITLE: Access Built-in Marp Core Instance in Functional Engine
DESCRIPTION: Shows how to use the `marp` getter property, exposed to the functional engine's constructor options, to access and apply customizations like plugins to the built-in Marp Core engine instance.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_31

LANGUAGE: javascript
CODE:
```
const marpPlugin = require('marp-plugin-foo')
const andMorePlugin = require('marp-plugin-bar')

module.exports = ({ marp }) => marp.use(marpPlugin).use(andMorePlugin)
```

----------------------------------------

TITLE: Render Basic HTML Tags
DESCRIPTION: This snippet demonstrates the use of basic HTML tags: the <b> tag for bold text and the <button> tag for an interactive button element. It shows how to nest a button within a bold tag, although this is not common practice. The purpose is to illustrate simple HTML structure.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/test/_configs/basic/md.md#_snippet_0

LANGUAGE: HTML
CODE:
```
<b>html<button>button</button></b>
```

----------------------------------------

TITLE: Specify Multiple Themes or Theme Directory in Marp CLI
DESCRIPTION: Details how to use the `--theme-set` option to register multiple theme CSS files or an entire theme directory. Registered themes become usable via Marpit's `theme` directive within Markdown decks.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_26

LANGUAGE: bash
CODE:
```
# Multiple theme CSS files
marp --theme-set theme-a.css theme-b.css theme-c.css -- deck-a.md deck-b.md
```

LANGUAGE: bash
CODE:
```
# Theme directory
marp --theme-set ./themes -- deck.md
```

----------------------------------------

TITLE: Marp CLI: Convert Markdown to HTML
DESCRIPTION: This snippet demonstrates the basic usage of Marp CLI to convert a Markdown file into an HTML file. By default, the output HTML file will be created in the same directory as the input Markdown file.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_5

LANGUAGE: bash
CODE:
```
marp slide-deck.md
```

----------------------------------------

TITLE: Configure Marp CLI using YAML (.marprc.yml)
DESCRIPTION: This snippet illustrates how to configure Marp CLI using a YAML file, such as `.marprc.yml`. It demonstrates enabling local file access and customizing Markdown parsing options, like disabling line breaks, providing a flexible way to manage settings outside of `package.json`.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_36

LANGUAGE: yaml
CODE:
```
# .marprc.yml
allowLocalFiles: true
options:
  looseYAML: false
  markdown:
    breaks: false
pdf: true
```

----------------------------------------

TITLE: Configure Marp CLI Browser Connection Options
DESCRIPTION: This section details command-line options for controlling browser behavior during Marp CLI operations. It includes settings for the preferred connection protocol and the timeout duration for browser-related tasks.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_18

LANGUAGE: APIDOC
CODE:
```
--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)
```

----------------------------------------

TITLE: Export presenter notes from Marp Markdown
DESCRIPTION: These commands demonstrate how to export presenter notes from Marp / Marpit Markdown. You can use the `--notes` option or specify an output path with a `.txt` extension to save the notes as a text file.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_13

LANGUAGE: bash
CODE:
```
# Export presenter notes as a text
marp --notes slide-deck.md
marp slide-deck.md -o output.txt
```

----------------------------------------

TITLE: Marp CLI: Convert Markdown to HTML with Custom Output Path
DESCRIPTION: This snippet shows how to specify a custom output path for the converted HTML file using the `--output` or `-o` option. The converted HTML will be saved to the specified file name.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_6

LANGUAGE: bash
CODE:
```
marp slide-deck.md -o output.html
```

----------------------------------------

TITLE: Marp CLI API: Waiting for Observation with waitForObservation()
DESCRIPTION: Explains how to use `waitForObservation()` to handle Marp CLI processes that involve ongoing observations like watch mode, server mode, or preview windows. It returns a Promise that resolves with a helper object containing a `stop()` method to terminate observations.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_46

LANGUAGE: javascript
CODE:
```
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 Promise
  stop()
})
```

----------------------------------------

TITLE: Define Async Functional Engine for Marp CLI
DESCRIPTION: Demonstrates how to use an async function for a functional engine. This allows for asynchronous operations, such as dynamic imports, when defining the custom engine.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_30

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

----------------------------------------

TITLE: Marp CLI: Convert Slide Deck to Multiple PNG/JPEG Images
DESCRIPTION: This snippet demonstrates converting a slide deck into multiple image files, either PNG or JPEG, using the `--images` option. Each slide will be saved as a separate image file with a page number suffix. The `--image-scale` option can be used to set the scale factor for higher resolution images.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_10

LANGUAGE: bash
CODE:
```
# Convert into multiple PNG image files
marp --images png slide-deck.md

# Convert into multiple JPEG image files
marp --images jpeg slide-deck.md
```

----------------------------------------

TITLE: Configure Marp CLI with Custom Engine in JavaScript
DESCRIPTION: Demonstrates how to define a `Config` type for Marp CLI in JavaScript, allowing for better type suggestions for the `options` field when using a custom Marpit-based engine. It uses JSDoc for type hinting.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_42

LANGUAGE: javascript
CODE:
```
/** @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
```

----------------------------------------

TITLE: Specify browser for Marp CLI conversions
DESCRIPTION: This snippet illustrates how to specify the browser for Marp CLI conversions using the `--browser` option. You can choose from `chrome`, `edge`, or `firefox`, or provide a comma-separated list to prioritize available browsers.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_16

LANGUAGE: bash
CODE:
```
# 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
```

----------------------------------------

TITLE: Enable local file access for Marp CLI conversions
DESCRIPTION: Due to security reasons, browser-based conversions in Marp CLI block local file access by default. This command shows how to use the `--allow-local-files` option to enable access for trusted Markdown files, acknowledging potential security risks.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_14

LANGUAGE: bash
CODE:
```
marp --pdf --allow-local-files slide-deck.md
```

----------------------------------------

TITLE: Define Marp CLI Metadata with Markdown Global Directives
DESCRIPTION: This snippet illustrates how to embed various metadata fields directly within a Markdown slide deck's front-matter. It demonstrates using Marp's global directives such as `title`, `description`, `author`, `keywords`, `url`, and `image` for comprehensive document information.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_23

LANGUAGE: markdown
CODE:
```
---
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
```

----------------------------------------

TITLE: Marp CLI: Convert Title Slide to Single PNG/JPEG Image
DESCRIPTION: This snippet shows how to convert only the first page (title slide) of a Markdown slide deck into a single image file. This can be done using the `--image` option or by specifying an output path with a PNG/JPEG extension. The `--image-scale` option can be used to set the scale factor for higher resolution images.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_11

LANGUAGE: bash
CODE:
```
# Convert the title slide into an image
marp --image png slide-deck.md
marp slide-deck.md -o output.png
```

----------------------------------------

TITLE: Configure Marp CLI with Custom Engine in TypeScript
DESCRIPTION: Illustrates how to configure Marp CLI using TypeScript (`marp.config.ts`). It shows how to specify a custom engine as a generic type for the `defineConfig` helper, enabling type-safe configuration and suggestions.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_43

LANGUAGE: typescript
CODE:
```
// 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
  },
})
```

----------------------------------------

TITLE: Generate high-resolution image with Marp CLI
DESCRIPTION: This command generates a high-resolution PNG image of the title slide using the `--image-scale` option. The scale factor applies to image and PPTX conversions, improving rendering quality without affecting the actual presentation size.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_12

LANGUAGE: bash
CODE:
```
marp slide-deck.md -o title-slide@2x.png --image-scale 2
```

----------------------------------------

TITLE: Set a global slide transition in Marp Markdown
DESCRIPTION: Demonstrates how to set a global slide transition effect, such as 'fade', for all subsequent slides in a Marp Markdown presentation by defining the `transition` local directive in the front matter.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_0

LANGUAGE: Markdown
CODE:
```
---
transition: fade
---

# First page

---

# Second page
```

----------------------------------------

TITLE: Define Custom Backward Transition Keyframes in CSS
DESCRIPTION: This snippet demonstrates how to define specific animation keyframes for backward navigation in Marp CLI using the `backward-` prefix. It shows a `triangle` transition with distinct incoming animations for forward and backward navigation, allowing for different visual effects based on navigation direction.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_6

LANGUAGE: CSS
CODE:
```
/* Define `triangle` transition */
@keyframes marp-incoming-transition-triangle {
  /* Wipe effect from left top */
  from {
    clip-path: polygon(0% 0%, 0% 0%, 0% 0%);
  }
  to {
    clip-path: polygon(0% 0%, 200% 0%, 0% 200%);
  }
}

@keyframes marp-incoming-transition-backward-triangle {
  /* Wipe effect from right bottom */
  from {
    clip-path: polygon(100% 100%, 100% 100%, 100% 100%);
  }
  to {
    clip-path: polygon(-100% 100%, 100% -100%, 100% 100%);
  }
}
```

----------------------------------------

TITLE: Change or disable slide transitions mid-presentation in Marp Markdown
DESCRIPTION: Illustrates how to dynamically change the slide transition effect (e.g., from 'fade' to 'cover') or disable it for a specific slide using HTML comments for local directives (`<!-- transition: cover -->`) or scoped local directives (`<!-- _transition: none -->`) within a Marp Markdown presentation.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_1

LANGUAGE: Markdown
CODE:
```
---
transition: fade
---

# Fade transition

---

<!-- transition: cover -->

Changed the kind of transition to `cover`.

---

<!-- _transition: none -->

Disabled transition for this slide.

---

Got back cover transition.
```

----------------------------------------

TITLE: Marp CLI API: Error Handling with CLIError and CLIErrorCode
DESCRIPTION: Documents the `CLIError` class and `CLIErrorCode` enum exported by `@marp-team/marp-cli` for specific error handling. Developers can check the `errorCode` member of a `CLIError` instance to identify the reason for a thrown error.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/README.md#_snippet_45

LANGUAGE: APIDOC
CODE:
```
CLIError: class
  Description: Represents an error thrown by Marp CLI with a specific error code.
  Properties:
    errorCode: CLIErrorCode
      Description: An enum value identifying the specific type of error.

CLIErrorCode: enum
  Description: Enumerates known error codes for Marp CLI.
  Source: https://github.com/marp-team/marp-cli/blob/main/src/error.ts
```

----------------------------------------

TITLE: Define Simple Marp Custom Transition with CSS Keyframes
DESCRIPTION: This CSS snippet shows how to define a simple custom transition in Marp using a single `@keyframes` declaration. The keyframe name must follow the `marp-transition-XXXXXXXX` pattern. This type of transition applies the defined animation to the current slide, and the new slide is animated in the opposite direction.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_3

LANGUAGE: css
CODE:
```
/* Define `dissolve` transition */
@keyframes marp-transition-dissolve {
  from {
    opacity: 1;
  }
  to {
    opacity: 0;
  }
}
```

----------------------------------------

TITLE: Define Split Marp Custom Transition with Outgoing/Incoming CSS Keyframes
DESCRIPTION: This CSS snippet illustrates how to define separate animations for outgoing and incoming slides in Marp transitions. By using `marp-outgoing-transition-XXXXXXXX` and `marp-incoming-transition-XXXXXXXX` keyframe prefixes, developers can create distinct animations for the current slide disappearing and the new slide appearing. The outgoing transition should declare a disappearing animation, and the incoming transition an appearing one.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_4

LANGUAGE: css
CODE:
```
/* Define `slide-up` transition */
/* WARN: Incomplete example. See also "Backward navigation". */
@keyframes marp-outgoing-transition-slide-up {
  from {
    transform: translateY(0%);
  }
  to {
    transform: translateY(-100%);
  }
}
@keyframes marp-incoming-transition-slide-up {
  from {
    transform: translateY(100%);
  }
  to {
    transform: translateY(0%);
  }
}
```

----------------------------------------

TITLE: Handle Backward Navigation in Marp Custom Transitions with CSS Variable
DESCRIPTION: This CSS snippet demonstrates how to create custom Marp transitions that behave differently for forward and backward navigation. By utilizing the `--marp-transition-direction` CSS custom property (which is `1` for forward and `-1` for backward), and `calc()` function, the animation's direction can be dynamically adjusted within the keyframes, providing a more natural user experience during navigation.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_5

LANGUAGE: css
CODE:
```
/* Define an improved `slide-up` transition, with better backward navigation */
@keyframes marp-outgoing-transition-slide-up {
  from {
    transform: translateY(0%);
  }
  to {
    transform: translateY(calc(var(--marp-transition-direction, 1) * -100%));
  }
}
@keyframes marp-incoming-transition-slide-up {
  from {
    transform: translateY(calc(var(--marp-transition-direction, 1) * 100%));
  }
  to {
    transform: translateY(0%);
  }
}
```

----------------------------------------

TITLE: Define Morphable Elements with view-transition-name in Marp Markdown
DESCRIPTION: This snippet demonstrates how to use the `view-transition-name` CSS property within a Marp Markdown presentation to mark specific image elements as morphable. It shows a CSS block defining a style for images with `alt="1"` to apply `view-transition-name: one;`, enabling a smooth morphing animation for the "1" icon across different slides.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_11

LANGUAGE: Markdown
CODE:
```
---
theme: gaia
transition: fade
style: |
  img[title~="step"] {
    height: 64px;
    position: relative;
    top: -0.1em;
    vertical-align: middle;
    width: 64px;

    /* ⬇️ Mark the image of "1" in every pages as morphable image named as "one" ⬇️ */
    &[alt="1"] {
      view-transition-name: one;
    }
  }
---

# Today's topics

- ![1](https://icongr.am/material/numeric-1-circle.svg?color=666666 'step') Introduction
- ![2](https://icongr.am/material/numeric-2-circle.svg?color=666666 'step') Features
- ![3](https://icongr.am/material/numeric-3-circle.svg?color=666666 'step') Conclusion

---

<!-- _class: lead -->

![1 w:256 h:256](https://icongr.am/material/numeric-1-circle.svg?color=ff9900 'step')

# Introduction

---

# ![1](https://icongr.am/material/numeric-1-circle.svg?color=666666 'step') Introduction

Marp is an open-sourced Markdown presentation ecosystem.

It provides a writing experience of presentation slides by Markdown.
```

----------------------------------------

TITLE: Disable Marp CLI Transitions via CLI Option
DESCRIPTION: This snippet demonstrates how to disable slide transitions in Marp CLI presentations. By adding the `--bespoke.transition=false` option to the `marp` command, users can opt out of the default transition effects. This is also useful when working with customized engines that handle transition directives differently.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_14

LANGUAGE: sh
CODE:
```
marp --bespoke.transition=false markdown.md
```

----------------------------------------

TITLE: Adjust Incoming Slide Layer Order with z-index in Marp CSS
DESCRIPTION: This code snippet explains how to control the stacking order of slide layers during a Marp transition. By setting `z-index: -1` within the incoming transition keyframes, the incoming slide layer can be sent to the back, which is useful for certain transition types where the default stacking order is not suitable.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_9

LANGUAGE: CSS
CODE:
```
@keyframes marp-incoming-transition-XXXXXXXX {
  from,
  to {
    z-index: -1;
  }
}
```

----------------------------------------

TITLE: Set Default Transition Duration in Marp CSS Keyframes
DESCRIPTION: This snippet demonstrates how to set a default duration for a custom Marp transition by defining the `--marp-transition-duration` CSS variable within the `from` or `0%` keyframe of the incoming transition. It also shows that a different duration can be set specifically for backward transitions, providing fine-grained control over animation timing.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_8

LANGUAGE: CSS
CODE:
```
/** Declare `gate` transition */
@keyframes marp-incoming-transition-gate {
  from {
    /* ⬇️ Set the default duration as 1 second. ⬇️ */
    --marp-transition-duration: 1s;

    clip-path: inset(0 50%);
  }
  to {
    clip-path: inset(0);
  }
}

@keyframes marp-outgoing-transition-backward-gate {
  from {
    /* You also can set a different duration for backward transition as necessary. */
    /* --marp-transition-duration: 1.5s; */

    clip-path: inset(0);
  }
  to {
    clip-path: inset(0 50%);
  }
}
@keyframes marp-incoming-transition-backward-gate {
  from,
  to {
    z-index: -1;
  }
}
```

----------------------------------------

TITLE: Set Custom Transition Duration in Marp YAML
DESCRIPTION: This YAML snippet demonstrates how to set a custom duration for a Marp slide transition. By appending a time value (e.g., `1s` or `500ms`) to the transition name, users can override the default `0.5s` duration for built-in transitions like `fade`.

SOURCE: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#_snippet_2

LANGUAGE: yaml
CODE:
```
transition: fade 1s
```