{"id":13407425,"url":"https://github.com/marp-team/marp-cli","last_synced_at":"2025-05-13T17:09:47.744Z","repository":{"id":33152961,"uuid":"144130157","full_name":"marp-team/marp-cli","owner":"marp-team","description":"A CLI interface for Marp and Marpit based converters","archived":false,"fork":false,"pushed_at":"2025-02-21T22:07:55.000Z","size":14285,"stargazers_count":2227,"open_issues_count":18,"forks_count":121,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-04-24T01:58:04.408Z","etag":null,"topics":["cli","deck","markdown","marp","marpit","presentation","slides"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marp-team.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["yhatt"]}},"created_at":"2018-08-09T09:22:36.000Z","updated_at":"2025-04-23T21:18:02.000Z","dependencies_parsed_at":"2023-01-14T23:45:30.019Z","dependency_job_id":"725f9ea2-1e09-46d1-b8a2-21b83c268eb9","html_url":"https://github.com/marp-team/marp-cli","commit_stats":{"total_commits":1753,"total_committers":22,"mean_commits":79.68181818181819,"dds":0.07358813462635483,"last_synced_commit":"6313b2a6155c71726f594e3cd2b81e056161c306"},"previous_names":[],"tags_count":121,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marp-team%2Fmarp-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marp-team%2Fmarp-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marp-team%2Fmarp-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marp-team%2Fmarp-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marp-team","download_url":"https://codeload.github.com/marp-team/marp-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253990468,"owners_count":21995774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","deck","markdown","marp","marpit","presentation","slides"],"created_at":"2024-07-30T20:00:39.896Z","updated_at":"2025-05-13T17:09:42.735Z","avatar_url":"https://github.com/marp-team.png","language":"TypeScript","readme":"# @marp-team/marp-cli\n\n[![CircleCI](https://img.shields.io/circleci/project/github/marp-team/marp-cli/main.svg?style=flat-square\u0026logo=circleci)](https://circleci.com/gh/marp-team/marp-cli/)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/marp-team/marp-cli/test-win.yml?branch=main\u0026style=flat-square\u0026logo=github)](https://github.com/marp-team/marp-cli/actions?query=workflow%3A%22Test+for+Windows%22+branch%3Amain)\n[![Codecov](https://img.shields.io/codecov/c/github/marp-team/marp-cli/main.svg?style=flat-square\u0026logo=codecov)](https://codecov.io/gh/marp-team/marp-cli)\n[![npm](https://img.shields.io/npm/v/@marp-team/marp-cli.svg?style=flat-square\u0026logo=npm)](https://www.npmjs.com/package/@marp-team/marp-cli)\n[![Docker](https://img.shields.io/docker/pulls/marpteam/marp-cli.svg?logo=docker\u0026style=flat-square)](https://hub.docker.com/r/marpteam/marp-cli/)\n[![LICENSE](https://img.shields.io/github/license/marp-team/marp-cli.svg?style=flat-square)](./LICENSE)\n\n**A CLI interface, for [Marp](https://github.com/marp-team/marp)** (using [@marp-team/marp-core](https://github.com/marp-team/marp-core)) and any slide deck converter based on [Marpit](https://marpit.marp.app/) framework.\n\nIt can convert Marp / Marpit Markdown files into static HTML / CSS, PDF, PowerPoint document, and image(s) easily.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/marp-team/marp-cli/main/docs/images/marp-cli.gif\" /\u003e\n\u003c/p\u003e\n\n## Try it now!\n\n### npx\n\n[npx (`npm exec`)](https://docs.npmjs.com/cli/commands/npx) is the best way to use the latest Marp CLI if you wanted\none-shot Markdown conversion _without install_. Just run below if you have\ninstalled [Node.js](https://nodejs.org/) v18 and later.\n\n```bash\n# Convert slide deck into HTML\nnpx @marp-team/marp-cli@latest slide-deck.md\nnpx @marp-team/marp-cli@latest slide-deck.md -o output.html\n\n# Convert slide deck into PDF\nnpx @marp-team/marp-cli@latest slide-deck.md --pdf\nnpx @marp-team/marp-cli@latest slide-deck.md -o output.pdf\n\n# Convert slide deck into PowerPoint document (PPTX)\nnpx @marp-team/marp-cli@latest slide-deck.md --pptx\nnpx @marp-team/marp-cli@latest slide-deck.md -o output.pptx\n\n# Watch mode\nnpx @marp-team/marp-cli@latest -w slide-deck.md\n\n# Server mode (Pass directory to serve)\nnpx @marp-team/marp-cli@latest -s ./slides\n```\n\n\u003e [!IMPORTANT]\n\u003e You have to install any one of [Google Chrome], [Microsoft Edge], or [Mozilla Firefox] to convert slide deck into PDF, PPTX, and image(s).\n\n[google chrome]: https://www.google.com/chrome/\n[microsoft edge]: https://www.microsoft.com/edge\n[mozilla firefox]: https://www.mozilla.org/firefox/new/\n\n### Container image\n\nDon't you like installing Node.js and Chrome to local? We have an official container image that is ready to use CLI.\n\n[**⏩ Please refer how to use at Docker Hub.**][marp-cli-docker]\n\n[marp-cli-docker]: https://hub.docker.com/r/marpteam/marp-cli/\n\n#### [Docker Hub][marp-cli-docker]\n\n```bash\ndocker pull marpteam/marp-cli\n```\n\n#### [GitHub Container Registry](https://github.com/marp-team/marp-cli/pkgs/container/marp-cli)\n\n```bash\ndocker pull ghcr.io/marp-team/marp-cli\n```\n\n## Install\n\n### Use package manager\n\nYou can use the package manager to install and update Marp CLI easily.\n\n_Disclaimer: Package manifests are maintained by the community, not Marp team._\n\n\u003c!-- For contributors: This section describes only package managers that Marp manifest has been actively maintained. Each tools are following update within a few days of the latest CLI update. --\u003e\n\n#### macOS: **[Homebrew](https://brew.sh/)**\n\n```bash\nbrew install marp-cli\n```\n\n\u003c!-- https://github.com/Homebrew/homebrew-core/blob/master/Formula/m/marp-cli.rb --\u003e\n\n#### Windows: **[Scoop](https://scoop.sh/)**\n\n```cmd\nscoop install marp\n```\n\n\u003c!-- https://github.com/ScoopInstaller/Main/blob/master/bucket/marp.json --\u003e\n\n### Local installation\n\nWe recommend to install Marp CLI into your Node.js project. You may control the CLI version (and engine if you want) exactly.\n\n```bash\nnpm install --save-dev @marp-team/marp-cli\n```\n\nThe installed `marp` command is available in [npm-scripts](https://docs.npmjs.com/misc/scripts) or `npx marp`.\n\n\u003e [!NOTE]\n\u003e Marp CLI is working only with [actively supported Node.js versions](https://endoflife.date/nodejs), so Node.js v18 and later is required when installing into your Node.js project.\n\n#### Global installation\n\nYou can install with `-g` option if you want to use `marp` command globally.\n\n```bash\nnpm install -g @marp-team/marp-cli\n```\n\n### [Standalone binary][releases]\n\nWe 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.\n\n**[⏩ Download the latest standalone binary from release page.][releases]**\n\n[releases]: https://github.com/marp-team/marp-cli/releases\n\n## Basic usage\n\n\u003e [!IMPORTANT]\n\u003e Several kind of conversions with 🌐 icon require to install any of compatible browsers, [Google Chrome], [Microsoft Edge], or [Mozilla Firefox]. When an unexpected problem has occurred while converting, please update your browser to the latest version. Check out [browser options](#browser-options) too.\n\n### Convert to HTML\n\nThe passed markdown will be converted to HTML file by default. In the below example, a converted `slide-deck.html` will output to the same directory.\n\n```bash\nmarp slide-deck.md\n```\n\nYou can change the output path by `--output` (`-o`) option.\n\n```bash\nmarp slide-deck.md -o output.html\n```\n\nMarp CLI supports converting multiple files by passing multiple paths, directories, and glob patterns. In this case, `--output` option cannot use.\n\nWhen 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.\n\n### Convert to PDF (`--pdf`) 🌐\n\nIf 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.\n\n```bash\nmarp --pdf slide-deck.md\nmarp slide-deck.md -o converted.pdf\n```\n\n#### PDF output options\n\n- **`--pdf-notes`**: Add PDF note annotations to the lower left when the slide page has [Marpit presenter notes].\n- **`--pdf-outlines`**: Add PDF outlines/bookmarks.\n\n`--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`.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/marp-team/marp-cli/main/docs/images/pdf-output-options.png\" width=\"500\" /\u003e\n\u003c/p\u003e\n\n[marpit presenter notes]: https://marpit.marp.app/usage?id=presenter-notes\n\n### Convert to PowerPoint document (`--pptx`) 🌐\n\nDo 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.\n\n```bash\nmarp --pptx slide-deck.md\nmarp slide-deck.md -o converted.pptx\n```\n\nA created PPTX includes rendered Marp slide pages and the support of [Marpit presenter notes]. It can open with PowerPoint, Keynote, Google Slides, LibreOffice Impress, and so on...\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/marp-team/marp-cli/main/docs/images/pptx.png\" height=\"300\" /\u003e\n\u003c/p\u003e\n\n#### _[EXPERIMENTAL]_ Generate editable pptx (`--pptx-editable`)\n\nA converted PPTX usually consists of pre-rendered background images, that is meaning **contents 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.\n\n```bash\nmarp --pptx --pptx-editable slide-deck.md\n```\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e The experimental `--pptx-editable` option requires installing both of the browser and [LibreOffice Impress](https://www.libreoffice.org/).\n\u003e\n\u003e If the theme and inline styles are providing complex styles into the slide, **`--pptx-editable` may throw an error or output the incomplete result.** (e.g. `gaia` theme in Marp Core)\n\n\u003e [!WARNING]\n\u003e\n\u003e Conversion to the editable PPTX results in **lower slide reproducibility compared to the conversion into regular PPTX and other formats.** Additionally, **presenter notes are not supported.** _We do not recommend to export the editable PPTX if maintaining the slide's appearance is important._\n\n### Convert to PNG/JPEG image(s) 🌐\n\n#### Multiple images (`--images`)\n\nYou can convert the slide deck into multiple images when specified `--images [png|jpeg]` option.\n\n```bash\n# Convert into multiple PNG image files\nmarp --images png slide-deck.md\n\n# Convert into multiple JPEG image files\nmarp --images jpeg slide-deck.md\n```\n\nOutput files have a suffix of page number, like `slide-deck.001.png`, `slide-deck.002.png`, and so on.\n\n#### Title slide (`--image`)\n\nWhen you passed `--image` option or specified the output path with PNG/JPEG extension, Marp CLI will convert _only the first page (title slide)_ of the targeted slide deck into an image.\n\n```bash\n# Convert the title slide into an image\nmarp --image png slide-deck.md\nmarp slide-deck.md -o output.png\n```\n\nIt would be useful for creating [Open Graph] image that can specify with [`image` global directive and `--og-image` option](#metadata).\n\n#### Scale factor\n\nYou can set the scale factor for rendered image(s) through `--image-scale` option. It is useful for making high-resolution image from the slide.\n\n```bash\n# Generate high-resolution image of the title slide\nmarp slide-deck.md -o title-slide@2x.png --image-scale 2\n```\n\n\u003e [!TIP]\n\u003e\n\u003e `--image-scale` is not affect to the actual size of presentation.\n\u003e\n\u003e The scale factor is also available for PPTX conversion. By default, Marp CLI will use `2` as the default scale factor in PPTX, to suppress deterioration of slide rendering in full-screen presentation.\n\n### Export presenter notes (`--notes`)\n\nYou can export [presenter notes][marpit presenter notes] in Marp / Marpit Markdown as a text file by using `--notes` option or specifying the output path with TXT extension.\n\n```bash\n# Export presenter notes as a text\nmarp --notes slide-deck.md\nmarp slide-deck.md -o output.txt\n```\n\n### Security about local files\n\nBecause of [the security reason](https://github.com/marp-team/marp-cli/pull/10#user-content-security), **conversion that is using the browser cannot use local files by default.**\n\nMarp CLI would output incomplete result with warning if the blocked local file accessing is detected. We recommend uploading your assets to online.\n\nIf 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._\n\n```bash\nmarp --pdf --allow-local-files slide-deck.md\n```\n\n## Conversion modes\n\n### Parallelism\n\nWhen 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`.\n\n### Watch mode (`--watch` / `-w`) \u003ca name=\"watch-mode\"\u003e\u003c/a\u003e\n\nMarp 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.\n\nWhile you are opening the converted HTML in browser, it would refresh the opened page automatically.\n\n### Server mode (`--server` / `-s`)\n\nServer mode supports on-demand conversion by HTTP request. We require to pass `--server` (`-s`) option and a directory to serve.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/marp-team/marp-cli/main/docs/images/server-mode.gif\" /\u003e\n\u003c/p\u003e\n\nIn this mode, the converted file outputs as the result of accessing to server, and not to disk.\n\nYou 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.\n\n\u003e [!TIP]\n\u003e\n\u003e You can set the server port by setting the environment variable `PORT`. For example, `PORT=5000 marp -s ./slides` would listen on port number 5000.\n\n#### `index.md` / `PITCHME.md`\n\nMarp 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`.\n\nPlace Markdown named `index.md` or `PITCHME.md` ([GitPitch style](https://gitpitch.github.io/gitpitch/#/conventions/pitchme-md)) to served directory. It would be redirected just accessing to `http://localhost:8080/`.\n\n### Preview window (`--preview` / `-p`)\n\nWhen conversions were executed together with `--preview` (`-p`) option, Marp CLI will open preview window(s) to check the converted result immediately.\n\nUnlike opening with browser, you may present deck with the immersive window.\n[Watch mode](#watch-mode) is automatically enabled while using preview window.\n\n\u003e [!NOTE]\n\u003e\n\u003e `--preview` option cannot use when you are using Marp CLI through official Docker image.\n\n## Browser options\n\n### Choose browser (`--browser`)\n\nYou 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.\n\n```bash\n# Use Firefox for image conversion\nmarp --browser firefox ./slide.md -o slide.png\n\n# Prefer to use Firefox first, then Chrome\nmarp --browser firefox,chrome ./slide.md -o slide.png\n```\n\nThe default is a special value `auto`, which means to use the first available browser from `chrome,edge,firefox`.\n\n\u003e [!WARNING]\n\u003e\n\u003e _Firefox support is still early stage._ The PDF output generated by Firefox may include some incompatible renderings compared to the PDF generated by Chrome.\n\n### Browser path (`--browser-path`)\n\nIf 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.\n\n```bash\n# Use Chromium-flavored browser (Chromium, Brave, Vivaldi, etc...)\nmarp --browser-path /path/to/chromium-flavored-browser ./slide.md -o slide.pdf\n\n# Use Firefox with explicitly set path\nmarp --browser firefox --browser-path /path/to/firefox ./slide.md -o slide.png\n```\n\n### Other browser options\n\n- **`--browser-protocol`**: Set the preferred protocol for connecting to the browser.\n  - `cdp`: [Chrome DevTools Protocol][cdp] (default)\n  - `webdriver-bidi`: [WebDriver BiDi]\n- **`--browser-timeout`**: Set the timeout for each browser operation in seconds. (default: `30` seconds)\n\n[cdp]: https://chromedevtools.github.io/devtools-protocol/\n[webdriver bidi]: https://w3c.github.io/webdriver-bidi/\n\n## Template\n\nYou can choose a built-in HTML templates by `--template` option. Default template is `bespoke`.\n\n```bash\nmarp --template bespoke slide-deck.md\n```\n\n### `bespoke` template (default)\n\nThe `bespoke` template is using [Bespoke.js](https://github.com/bespokejs/bespoke) as the name implies. It has several features to be useful in a real presentation. A few features may control by CLI options.\n\n#### Features\n\n- **Navigation**: Navigate the deck through keyboard and swipe geasture.\n- **Fullscreen**: Toggle fullscreen by hitting \u003ckbd\u003ef\u003c/kbd\u003e / \u003ckbd\u003eF11\u003c/kbd\u003e key.\n- **On-screen controller**: There is a touch-friendly OSC. You may also disable by `--bespoke.osc=false` if unneccesary.\n- **Fragmented list**: Recognize [Marpit's fragmented list](https://github.com/marp-team/marpit/issues/145) and appear list one-by-one if used `*` and `1)` as the bullet marker.\n- **Presenter view**: Open presenter view in external window by hitting \u003ckbd\u003ep\u003c/kbd\u003e key. (It may become disabled when not fulfilled requirements for working)\n- **Progress bar** (optional): By setting `--bespoke.progress` option, you can add a progress bar on the top of the deck.\n- [**Slide transitions**][transitions]: Support transitions (`transition` local directive) powered by [View Transition API].\n\n[transitions]: ./docs/bespoke-transitions/README.md\n[view transition api]: https://www.w3.org/TR/css-view-transitions-1/\n\n#### Docs\n\n- **[Slide transitions in `bespoke` template][transitions]**\u003cbr /\u003e\n  Learn all about of slide transitions for `bespoke` template: Built-in transitions, custom transitions, and morphing animations.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"./docs/bespoke-transitions/README.md\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/marp-team/marp-cli/main/docs/bespoke-transitions/images/morphing-animation.gif\" width=\"320\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n### `bare` template\n\nThe `bare` template is a primitive template, and there is no extra features. It only has minimum assets to give your presentation with browser.\n\n#### Zero-JS slide deck\n\nWhen [the conversion engine is changed to Marpit framework by setting `engine` option](#use-marpit-framework), _it would not use any scripts._ Even then, it has enough to use for the browser-based presentation.\n\n```bash\nmarp --template bare --engine @marp-team/marpit slide-deck.md\n```\n\n## Metadata\n\nThrough [global directives] or CLI options, you can set metadata for a converted HTML, PDF, and PPTX slide deck.\n\n| [Global directives] |   CLI option    | Description                     | Available in    |\n| :-----------------: | :-------------: | :------------------------------ | :-------------- |\n|       `title`       |    `--title`    | Define title of the slide deck  | HTML, PDF, PPTX |\n|    `description`    | `--description` | Define description of the slide | HTML, PDF, PPTX |\n|      `author`       |   `--author`    | Define author of the slide deck | HTML, PDF, PPTX |\n|     `keywords`      |  `--keywords`   | Define comma-separated keywords | HTML, PDF       |\n|        `url`        |     `--url`     | Define [canonical URL]          | HTML            |\n|       `image`       |  `--og-image`   | Define [Open Graph] image URL   | HTML            |\n\n[canonical url]: https://en.wikipedia.org/wiki/Canonical_link_element\n[open graph]: http://ogp.me/\n\n### By [global directives]\n\nMarp CLI supports _additional [global directives]_ to specify metadata in Markdown. You can define meta values in Markdown front-matter.\n\n```markdown\n---\ntitle: Marp slide deck\ndescription: An example slide deck created by Marp CLI\nauthor: Yuki Hattori\nkeywords: marp,marp-cli,slide\nurl: https://marp.app/\nimage: https://marp.app/og-image.jpg\n---\n\n# Marp slide deck\n```\n\n[global directives]: https://marpit.marp.app/directives?id=global-directives-1\n\n### By CLI option\n\nMarp CLI prefers CLI option to global directives. You can override metadata values by `--title`, `--description`, `--author`, `--keywords`, `--url`, and `--og-image`.\n\n## Theme\n\n### Override theme\n\nYou can override theme you want to use by `--theme` option. For example to use [Gaia](https://github.com/marp-team/marp-core/tree/main/themes#gaia) built-in theme in Marp Core:\n\n```bash\nmarp --theme gaia\n```\n\n### Use custom theme\n\nA custom theme created by user also can use easily by passing the path of CSS file.\n\n```bash\nmarp --theme custom-theme.css\n```\n\n\u003e [!TIP]\n\u003e\n\u003e [Marpit theme CSS requires `@theme` meta comment](https://marpit.marp.app/theme-css?id=metadata) in regular use, but it's not required in this usage.\n\n### Theme set\n\n`--theme-set` option has to specify theme set composed by multiple theme CSS files. The registed themes are usable in [Marpit's `theme` directive](https://marpit.marp.app/directives?id=theme).\n\n```bash\n# Multiple theme CSS files\nmarp --theme-set theme-a.css theme-b.css theme-c.css -- deck-a.md deck-b.md\n\n# Theme directory\nmarp --theme-set ./themes -- deck.md\n```\n\n## Engine\n\nMarp CLI is calling the [Marpit framework](https://marpit.marp.app/) based converter as \"Engine\". Normally we use the bundled [Marp Core](https://github.com/marp-team/marp-core), but you may swap the conversion engine to another Marpit based engine through `--engine` option.\n\nYou 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.\n\n### Use Marpit framework\n\nFor example, you can convert Markdown with using the pure Marpit framework.\n\n```bash\n# Install Marpit framework\nnpm i @marp-team/marpit\n\n# Specify engine to use Marpit\nmarp --engine @marp-team/marpit marpit-deck.md\n```\n\nNotice that Marpit has not provided theme. It would be good to include inline style in Markdown, or pass CSS file by `--theme` option.\n\n\u003e [!TIP]\n\u003e\n\u003e If you want to use the Marpit-based custom engine by the module name, the specified module must be exporting a class inherited from Marpit as the default export.\n\n### Functional engine\n\nWhen you specified the path to JavaScript file (`.js`, `.cjs`, or `.mjs`) in `--engine` option, you may use more customized engine by a JavaScript function.\n\n#### Spec\n\nThe functional engine should export a function as the default export, which should have a single argument representing [the constructor option of Marpit](https://marpit-api.marp.app/marpit)/[Marp Core](https://github.com/marp-team/marp-core#constructor-options).\n\nThe function must return a class inherited from Marpit, or an instance of Marpit-based engine made by the parameter passed by argument.\n\n```javascript\n// engine.mjs (ES modules)\nimport { MarpitBasedEngine } from 'marpit-based-engine'\n\nexport default () =\u003e MarpitBasedEngine // Return a class inherited from Marpit\n```\n\n```javascript\n// engine.cjs (CommonJS)\nconst { MarpitBasedEngine } = require('marpit-based-engine')\n\nmodule.exports = function (constructorOptions) {\n  // Return an instance of Marpit initialized by passed constructor options\n  return new MarpitBasedEngine(constructorOptions)\n}\n```\n\nThis function can return [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) object so you can use [async function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) too.\n\n```javascript\nexport default async (constructorOptions) =\u003e {\n  const { MarpitBasedEngine } = await import('marpit-based-engine')\n  return new MarpitBasedEngine(constructorOptions)\n}\n```\n\n\u003e [!WARNING]\n\u003e\n\u003e Currently ES Modules can resolve only when using Marp CLI via Node.js. [The standalone binary](#standalone-binary) cannot resolve ESM. ([vercel/pkg#1291](https://github.com/vercel/pkg/issues/1291))\n\n#### `marp` getter property\n\nMarp 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.\n\n```javascript\nconst marpPlugin = require('marp-plugin-foo')\nconst andMorePlugin = require('marp-plugin-bar')\n\nmodule.exports = ({ marp }) =\u003e marp.use(marpPlugin).use(andMorePlugin)\n```\n\nIt allows converting Markdown with additional syntaxes that were provided by Marp (or compatible markdown-it) plugins.\n\n#### Example: [markdown-it-mark](https://github.com/markdown-it/markdown-it-mark)\n\n```javascript\n// engine.mjs\nimport markdownItMark from 'markdown-it-mark'\n\nexport default ({ marp }) =\u003e marp.use(markdownItMark)\n```\n\n```bash\n# Install markdown-it-mark into your project\nnpm i markdown-it-mark --save\n\n# Specify the path to functional engine\nmarp --engine ./engine.mjs slide-deck.md\n```\n\nThe customized engine will convert `==marked==` to `\u003cmark\u003emarked\u003c/mark\u003e`.\n\n### Confirm engine version\n\nBy using `--version` (`-v`) option, you may confirm the version of engine that is expected to use in current configuration.\n\n```console\n$ marp --version\n@marp-team/marp-cli v4.x.x (w/ @marp-team/marp-core v4.x.x)\n```\n\n### Use specific version of Marp Core\n\nMarp CLI prefers to use _an installed core to local project by user_ than the bundled.\n\nIf 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`.\n\n```console\n$ npm i @marp-team/marp-cli @marp-team/marp-core@^4.0.0 --save-dev\n$ npx marp --version\n@marp-team/marp-cli v4.x.x (w/ user-installed @marp-team/marp-core v4.0.0)\n```\n\n## Configuration file\n\nMarp 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`.\n\nIt is useful to configure settings for the whole of project.\n\n```javascript\n// package.json\n{\n  \"marp\": {\n    \"inputDir\": \"./slides\",\n    \"output\": \"./public\",\n    \"themeSet\": \"./themes\"\n  }\n}\n```\n\n```yaml\n# .marprc.yml\nallowLocalFiles: true\noptions:\n  looseYAML: false\n  markdown:\n    breaks: false\npdf: true\n```\n\n```javascript\n// marp.config.mjs\nimport markdownItContainer from 'markdown-it-container'\n\nexport default {\n  // Customize engine on configuration file directly\n  engine: ({ marp }) =\u003e marp.use(markdownItContainer, 'custom'),\n}\n```\n\nBy 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.\n\nIf you want to prevent looking up a configuration file, you can pass `--no-config-file` (`--no-config`) option.\n\n\u003e [!WARNING]\n\u003e\n\u003e Currently ES Modules can resolve only when using Marp CLI via Node.js. [The standalone binary](#standalone-binary) cannot resolve ESM. ([vercel/pkg#1291](https://github.com/vercel/pkg/issues/1291))\n\n### Options\n\n| Key               |            Type             |        CLI option         | Description                                                                                                 |\n| :---------------- | :-------------------------: | :-----------------------: | :---------------------------------------------------------------------------------------------------------- |\n| `allowLocalFiles` |           boolean           |   `--allow-local-files`   | Allow to access local files from Markdown while converting PDF _(NOT SECURE)_                               |\n| `author`          |           string            |        `--author`         | Define author of the slide deck                                                                             |\n| `bespoke`         |           object            |                           | Setting options for `bespoke` template                                                                      |\n| ┗ `osc`           |           boolean           |      `--bespoke.osc`      | \\[Bespoke\\] Use on-screen controller (`true` by default)                                                    |\n| ┗ `progress`      |           boolean           |   `--bespoke.progress`    | \\[Bespoke\\] Use progress bar (`false` by default)                                                           |\n| ┗ `transition`    |           boolean           |  `--bespoke.transition`   | \\[Bespoke\\] Use [transitions] (Only in browsers supported [View Transition API]: `true` by default)         |\n| `browser`         |     string \\| string[]      |        `--browser`        | The kind of browser for conversion (`auto` by default)                                                      |\n| `browserPath`     |           string            |     `--browser-path`      | Path to the browser executable                                                                              |\n| `browserProtocol` |  `cdp` \\| `webdriver-bidi`  |   `--browser-protocol`    | Set the preferred protocol for connecting to the browser (`cdp` by default)                                 |\n| `browserTimeout`  |           number            |    `--browser-timeout`    | Set the timeout for each browser operation in seconds (`30` by default)                                     |\n| `description`     |           string            |      `--description`      | Define description of the slide deck                                                                        |\n| `engine`          | string \\| Class \\| Function |        `--engine`         | Specify Marpit based engine                                                                                 |\n| `html`            |      boolean \\| object      |         `--html`          | Enable or disable HTML tags (Configuration file can pass [the whitelist object] if you are using Marp Core) |\n| `image`           |       `png` \\| `jpeg`       |         `--image`         | Convert the first slide page into an image file                                                             |\n| `images`          |       `png` \\| `jpeg`       |        `--images`         | Convert slide deck into multiple image files                                                                |\n| `imageScale`      |           number            |      `--image-scale`      | The scale factor for rendered images (`1` by default, or `2` for PPTX conversion)                           |\n| `inputDir`        |           string            |    `--input-dir` `-I`     | The base directory to find markdown and theme CSS                                                           |\n| `jpegQuality`     |           number            |     `--jpeg-quality`      | Setting JPEG image quality (`85` by default)                                                                |\n| `keywords`        |     string \\| string[]      |       `--keywords`        | Define keywords for the slide deck (Accepts comma-separated string and array of string)                     |\n| `lang`            |           string            |                           | Define the language of converted HTML                                                                       |\n| `notes`           |           boolean           |         `--notes`         | Convert slide deck notes into a text file                                                                   |\n| `ogImage`         |           string            |       `--og-image`        | Define [Open Graph] image URL                                                                               |\n| `options`         |           object            |                           | The base options for the constructor of engine                                                              |\n| `output`          |           string            |      `--output` `-o`      | Output file path (or directory when input-dir is passed)                                                    |\n| `parallel`        |      boolean \\| number      |     `--parallel` `-P`     | Set the number of concurrency for parallel conversion (`5` by default)                                      |\n| `pdf`             |           boolean           |          `--pdf`          | Convert slide deck into PDF                                                                                 |\n| `pdfNotes`        |           boolean           |       `--pdf-notes`       | Add [presenter notes][marpit presenter notes] to PDF as annotations                                         |\n| `pdfOutlines`     |      boolean \\| object      |     `--pdf-outlines`      | Add outlines (bookmarks) to PDF                                                                             |\n| ┗ `pages`         |           boolean           |  `--pdf-outlines.pages`   | Make PDF outlines from slide pages (`true` by default when `pdfOutlines` is enabled)                        |\n| ┗ `headings`      |           boolean           | `--pdf-outlines.headings` | Make PDF outlines from Markdown headings (`true` by default when `pdfOutlines` is enabled)                  |\n| `pptx`            |           boolean           |         `--pptx`          | Convert slide deck into PowerPoint document                                                                 |\n| `pptxEditable`    |           boolean           |     `--pptx-editable`     | _[EXPERIMENTAL]_ Generate editable PPTX when converting to PPTX                                             |\n| `preview`         |           boolean           |     `--preview` `-p`      | Open preview window                                                                                         |\n| `server`          |           boolean           |      `--server` `-s`      | Enable server mode                                                                                          |\n| `template`        |     `bare` \\| `bespoke`     |       `--template`        | Choose template (`bespoke` by default)                                                                      |\n| `theme`           |           string            |         `--theme`         | Override theme by name or CSS file                                                                          |\n| `themeSet`        |     string \\| string[]      |       `--theme-set`       | Path to additional theme CSS files                                                                          |\n| `title`           |           string            |         `--title`         | Define title of the slide deck                                                                              |\n| `url`             |           string            |          `--url`          | Define [canonical URL]                                                                                      |\n| `watch`           |           boolean           |      `--watch` `-w`       | Watch input markdowns for changes                                                                           |\n\n[the whitelist object]: https://github.com/marp-team/marp-core#html-boolean--object\n\nSome of options that cannot specify through CLI options can be configured by file. (e.g. `options` field for the constructor option of used engine)\n\n\u003cdetails\u003e\n\u003csummary\u003eExample: Customize engine's constructor option\u003c/summary\u003e\n\nYou can fine-tune constructor options for the engine, [Marp Core](https://github.com/marp-team/marp-core#constructor-options) / [Marpit](https://marpit-api.marp.app/marpit).\n\n```json\n{\n  \"options\": {\n    \"markdown\": {\n      \"breaks\": false\n    },\n    \"minifyCSS\": false\n  }\n}\n```\n\nThis configuration will set the constructor option for Marp Core as specified:\n\n- Disables [Marp Core's line breaks conversion](https://github.com/marp-team/marp-core#marp-markdown) (`\\n` to `\u003cbr /\u003e`) to match for CommonMark, by passing [markdown-it's `breaks` option](https://markdown-it.github.io/markdown-it/#MarkdownIt.new) as `false`.\n- Disable minification for rendered theme CSS to make debug your style easily, by passing [`minifyCSS`](https://github.com/marp-team/marp-core#minifycss-boolean) as `false`.\n\n\u003e [!WARNING]\n\u003e\n\u003e Some options may be overridden by used template.\n\n\u003c/details\u003e\n\n### Auto completion\n\nWhen Marp CLI has been installed into the local project, for getting the power of auto completion for the config, such as [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense), you can annotate the config object through JSDoc, with Marp CLI's `Config` type.\n\n```javascript\n/** @type {import('@marp-team/marp-cli').Config} */\nconst config = {\n  // ...\n}\n\nexport default config\n```\n\nOr you can import Vite-like `defineConfig` helper from Marp CLI instead.\n\n```javascript\nimport { defineConfig } from '@marp-team/marp-cli'\n\nexport default defineConfig({\n  // ...\n})\n```\n\n#### `Config` type with custom engine\n\nIf 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.\n\n```javascript\n/** @type {import('@marp-team/marp-cli').Config\u003ctypeof import('@marp-team/marpit').Marpit\u003e} */\nconst config = {\n  engine: '@marp-team/marpit',\n  options: {\n    // Suggest only Marpit constructor options, not Marp Core\n  },\n}\n\nexport default config\n```\n\n#### TypeScript (`marp.config.ts`)\n\nIf you installed `typescript` into your local project together with Marp CLI, you can write a config by TypeScript `marp.config.ts`. Marp CLI will try to transpile `.ts` with the project configuration `tsconfig.json`.\n\nIn TypeScript configuration, you can specify the custom engine as the generics for `defineConfig` helper, like this:\n\n```typescript\n// marp.config.ts\nimport { Marpit } from '@marp-team/marpit'\nimport { defineConfig } from '@marp-team/marp-cli'\n\nexport default defineConfig\u003ctypeof Marpit\u003e({\n  engine: Marpit,\n  options: {\n    // Suggest only Marpit constructor options\n  },\n})\n```\n\n## API _(EXPERIMENTAL)_\n\nYou can use Marp CLI through Node.js [if installed Marp CLI into your local project](#local-installation).\n\n```js\nconst { marpCli } = require('@marp-team/marp-cli')\n\nmarpCli(['test.md', '--pdf'])\n  .then((exitStatus) =\u003e {\n    if (exitStatus \u003e 0) {\n      console.error(`Failure (Exit status: ${exitStatus})`)\n    } else {\n      console.log('Success')\n    }\n  })\n  .catch(console.error)\n```\n\n`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.\n\n### Error handling\n\nWe have exported [`CLIError` class and `CLIErrorCode` enum](https://github.com/marp-team/marp-cli/blob/main/src/error.ts) from `@marp-team/marp-cli`, to allow handling for specific errors that have already known by Marp CLI.\n\nIf `CLIError` instance was thrown, you can identify the reason why CLI throwed error by checking `errorCode` member.\n\n### Wait for observation\n\n`marpCli()` would not be resolved initiatively if started some observation: Watch mode, server mode, and preview window.\n\n`waitForObservation()` is helpful to handle them. It returns `Promise` that would be resolved with helper object when ready to observe resources in `marpCli()`.\n\n```javascript\nconst { marpCli, waitForObservation } = require('@marp-team/marp-cli')\n\nmarpCli(['--server', './slides/'])\n  .then((exitCode) =\u003e console.log(`Done with exit code ${exitCode}`))\n  .catch(console.error)\n\nwaitForObservation().then(({ stop }) =\u003e {\n  console.log('Observed')\n\n  // Stop observations to resolve marpCli()'s Promise\n  stop()\n})\n```\n\nThe resolved helper has `stop()` method for telling Marp CLI to stop observation and resolve `Promise`.\n\n## Contributing\n\nAre you interested in contributing? Please see [CONTRIBUTING.md](.github/CONTRIBUTING.md) and [the common contributing guideline for Marp team](https://github.com/marp-team/.github/blob/master/CONTRIBUTING.md).\n\n## Author\n\nManaged by [@marp-team](https://github.com/marp-team).\n\n- \u003cimg src=\"https://github.com/yhatt.png\" width=\"16\" height=\"16\"/\u003e Yuki Hattori ([@yhatt](https://github.com/yhatt))\n\n## License\n\nThis tool releases under the [MIT License](LICENSE).\n","funding_links":["https://github.com/sponsors/yhatt"],"categories":["Productivity Tools","How To Use","TypeScript","Presentations","markdown","cli","🙌 Marp をもっと楽しむ 🙌","格式转换 Format","Productivity","Ecosystem"],"sub_categories":["**[1st step]** Create Slides-deck project","4. スライドの編集・確認","Presentations","Official"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarp-team%2Fmarp-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarp-team%2Fmarp-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarp-team%2Fmarp-cli/lists"}