Introducing Marp CLI v4 ✨

[yhatt]

We're happy to introduce a major update Marp CLI v4! This update brings serveral notable updates. 😆

👉 https://github.com/marp-team/marp-cli/releases/tag/v4.0.0

⚡ Breaking changes

Node.js 18 and later is required

Marp CLI v4 requires Node.js 18 or later. If you are using outdated Node.js 16 or earlier, you need to upgrade Node.js.

Integrated with new Marp Core v4

Marp Core v4 has been integrated into new CLI. It means that some breaking changes in new core may affect to your slides. Check out #533 to learn about following changes:

• The slide element now has display: block
• Safe centering
• Relaxed HTML usage
• Initial support for CSS nesting

The container image has been updated to Debian-based image

For more stable conversions, we have updated the Marp CLI container image to use a Debian base image instead of Alpine Linux.

If your Docker workflow uses the Marp CLI container image, you may need to update your workflow, as some commands may assume an Alpine environment.

New features

Initial support for Firefox 🦊

For a long time, Marp CLI has depended on Google Chrome or some Chromium-flavored browser such as Microsoft Edge, to render slides into PDF and several image formats. We are happy to announce that v4 added initial support for converting slides by Firefox! 🦊

A new --browser option allows you to specify the browser for Markdown conversion. Marp CLI will automatically detect the installed Firefox browser on your system.

marp --images png --browser firefox ./slide.md

The default value of --browser is auto, which means that Marp CLI will try to find a possible browser automatically. Google Chrome and Microsoft Edge will still be preferred as before, but Firefox will be used as a fallback if they are not found.

Firefox support is backed by WebDriver BiDi, a new standard protocol for browser automation. To support that, we have rewritten the browser management system in Marp CLI.

Warning

Currently, Firefox produces better conversion results when converting to image formats. However, when converting to PDF, you may encounter some rendering issues compared to PDFs generated by Chrome.

Browser options

Marp CLI v4 also introduces some new options to control the browser for conversion. The main use cases are as follows:

Browser path

--browser-path option can explicitly specify the path to the browser executable.

marp --pdf --browser-path /path/to/google-chrome ./slide.md

It has the same meaning as the CHROME_PATH environment variable up to v3, but it's more explicit and can apply to any browser. To set the path to Firefox, set the --browser-path option together with --browser firefox.

marp --images png --browser firefox --browser-path /path/to/firefox ./slide.md

CHROME_PATH and FIREFOX_PATH env still work when finding each browser, but we recommend using the new --browser-path option to make clear intent.

WebDriver BiDi for Chrome

When using Chrome or a Chromium-based browser, the default protocol for connecting to the browser is the Chrome DevTools Protocol, as used previously. A new --browser-protocol option can choose the preferred protocol to use in conversion.

This example will prefer to use WebDriver BiDi for connecting to browsers, including Chrome:

marp --pdf --browser-protocol webdriver-bidi ./slide.md

--browser-protocol=webdriver-bidi might become a default in a future release.

Timeout

Trying to convert large slide decks? If the default timeout for each browser operation (30 seconds) is not enough, you can extend it by specifying the --browser-timeout option. The following command will wait for 300 seconds for the conversion.

marp --pdf --browser-timeout 300 ./slide.md

If you specified --no-browser-timeout or --browser-timeout=0, Marp CLI will wait indefinitely until the conversion is completed.

WSL2 mirrored mode networking

If you are using Marp CLI over WSL 2, normally you cannot use browsers installed in Windows. Marp CLI cannot communicate with the Windows browser over WebSocket due to individual network interfaces and firewalls for each OS. (#113)

This restriction has been there in WSL 2 for a while, but now you can be mitigated by the mirrored mode networking setting.

If you enable it in %USERPROFILE%\.wslconfig, Marp CLI in WSL 2 will try to connect to the Windows browser when compatible browsers are not found in Linux.

# %USERPROFILE%\.wslconfig
[wsl2]
networkingMode=mirrored

That allows you to use a Windows browser during conversion, without downgrading to WSL 1. To apply changes, you may have to run wsl --shutdown and re-launch WSL.

Other changes

• Adopt new headless mode for Chrome by default (Chrome will remove the classic headless mode support in 2024)
• --debug (-d) option to access debug logs of Marp CLI
• The container image is available on GitHub Container Registry: ghcr.io/marp-team/marp-cli

What's next?

Marp CLI v4 major update was focusing on improvement of browser support. In upcoming minor updates, we are planning to make faster batch conversion by parallelism, improvement of PPTX export, and more.

[SoumayaMauthoorMOJ]

Hello @yhatt that's great news! justify-content: flex-start; doesn't seem to work for me any more, although I haven't published in a while so it could be related to another change. What css should I use to make sure the text aligns to the start?

[yhatt]

An integrated Marp Core v4 no longer uses Flexbox. justify-content CSS property does not affect block containers so you have to use align-content: start; instead.

[SoumayaMauthoorMOJ]

thank you!

[alanlivio]

That is amazing @yhatt. 🥳🥳🥳

[Beurt]

Hi,

Thank you very much! I am found of the idea of using Firefox instead of Chrome/Chromium. But I cannot manage to do it.

When I use --browser firefox --browser-path /usr/bin/firefox marp-cli returns

[  INFO ] Converting 1 markdown...
[  INFO ] test.md => test.html
[  INFO ] [Watch mode] Start watching...
[  INFO ] [Preview] Opening file:///XXXX....
[ ERROR ] No browser found for preview

Should I open an issue?

[yhatt]

Firefox support has been focused only for usage in Markdown conversion at the initial v4 release, so it's expected result for now. The preview window is not yet compatible because that is still depending on Chrome and Chrome DevTools Protocol (CDP).

We cannot promise to implement that immediately, but creating an issue is ok to track the progress.