Total Pageviews

Monday, 22 May 2023

Markdown幻灯片制作工具-Marp



Marp 是一款开源的简易幻灯片制作工具，特色是通过 Markdown 语法来编写演示幻灯片. 基于CoffeeScript开发, 遵守MIT开源协议。三种预览模式，还可以更换样式主题。多平台支持包括：Windows，Linux 和 MacOSX，支持数学公式以及 emoji 表情，支持PDF格式输出。

[repo owner=”yhatt” name=”marp”]

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

The site of classic Markdown presentation writer app

yhatt.github.io/marp/ 

It's a time to migrate into Marp Next!

The publication of classic Marp app has ended.

Marp desktop app, a simple Markdown presentation writer, already had stopped maintenance since 2017. Today Marp team is focusing into Marp Next project, the brand-new presentation ecosystem for the future.

See more details in our blog post.

Why?

We had kept publishing app for stuck users that are thinking Marp Next is too complex.

But recently, we received a serious security report for outdated app. By opening a malicious Markdown, an attacker can execute arbitrary code through remote. We are responsible for saving users from malicious.

If you are currently using Marp app, please stop using as soon as possible and migrate into well-maintained Marp Next tools.

Marp Next tools

Marp Next is not complex! Simply you can just use either one if you want to create slide deck.

Marp for VS Code (Recommended)

Marp for VS Code, an extension for Visual Studio Code, is the best alternative for desktop app users. There are key features inherited from the classic Marp app.

  • Live preview
  • Export to PDF, HTML, and PPTX (via Marp CLI)
  • Support built-in 3 themes and custom theme CSS

Marp CLI

Marp CLI is simple but powerful CLI converter from Marp Markdown into PDF, HTML, PPTX, and images. You can use it if you don't want GUI editor.

I also have an example repository to automate generating slide deck and serving through Marp CLI + Netlify or ZEIT Now.

Migrate Markdown

Marp Next is losing Markdown compatibility with classic app, but your slide would keep appearance as before just by some changes in most cases. Please see our blog post for details.

from https://github.com/yhatt/marp

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

A CLI interface for Marp and Marpit based converters  .

@marp-team/marp-cli

A CLI interface, for Marp (using @marp-team/marp-core) and any slide deck converter based on Marpit framework.

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

Try it now!

npx

npx (npm exec) is the best way to use the latest Marp CLI if you wanted one-shot Markdown conversion without install. Just run below if you have installed Node.js 14 and later.

# Convert slide deck into HTML
npx @marp-team/marp-cli@latest slide-deck.md
npx @marp-team/marp-cli@latest slide-deck.md -o output.html

# Convert slide deck into PDF
npx @marp-team/marp-cli@latest slide-deck.md --pdf
npx @marp-team/marp-cli@latest slide-deck.md -o output.pdf

# Convert slide deck into PowerPoint document (PPTX)
npx @marp-team/marp-cli@latest slide-deck.md --pptx
npx @marp-team/marp-cli@latest slide-deck.md -o output.pptx

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

# Server mode (Pass directory to serve)
npx @marp-team/marp-cli@latest -s ./slides

ℹ️ You have to install Google Chrome or Microsoft Edge to convert slide deck into PDF, PPTX, and image(s).

Install

Use package manager

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

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

macOS: Homebrew

brew install marp-cli

Windows: Scoop

scoop install marp

Local installation

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

ℹ️ Marp CLI is working only with actively supported Node.js versions, so Node.js 14 and later is required when installing into your Node.js project.

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

The installed marp command is available in npm-scripts or npx marp.

Global installation

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

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

Standalone binary

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

⏩ Download the latest standalone binary from release page.

Basic usage

Convert to HTML

The 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.

marp slide-deck.md

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

marp slide-deck.md -o output.html

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

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

Convert to PDF (--pdf)

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

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

All kind of conversions except HTML require to install Google Chrome, Microsoft Edge, or Chromium (flavored) browser. When an unexpected problem has occurred while converting, please update your browser to the latest version or try installing Google Chrome Canary.

ℹ️ If you want to use Chromium or flavored browsers to convert, you have to specify the path to the browser binary through CHROME_PATH environment variable. For example: CHROME_PATH=$(which brave) marp --pdf slide-deck.md

PDF output options

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

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

Convert to PowerPoint document (--pptx)

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

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

A 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...

ℹ️ A converted PPTX consists of pre-rendered images. Please note that contents would not be able to modify or re-use in PowerPoint.

Convert to PNG/JPEG image(s)

Multiple images (--images)

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

# Convert into multiple PNG image files
marp --images png slide-deck.md

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

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

Title slide (--image)

When 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.

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

It would be useful for creating Open Graph image that can specify with image global directive and --og-image option.

Scale factor

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

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

ℹ️ --image-scale is not affect to the actual size of presentation.

It 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.

Export presenter notes (--notes)

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

# Export presenter notes as a text
marp --notes slide-deck.md
marp slide-deck.md -o output.txt

Security about local files

Because of the security reason, PDF, PPTX and image(s) conversion cannot use local files by default.

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

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

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

Conversion modes

Watch mode (--watch / -w)

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

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

Server mode (--server / -s)

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

In this mode, the converted file outputs as the result of accessing to server, and not to disk. You can set the server port by setting the environment variable PORT, for example PORT=5000 marp -s ./slides would listen on port number 5000.

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

index.md / PITCHME.md

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

Place Markdown named index.md or PITCHME.md (GitPitch style) to served directory. It would be redirected just accessing to http://localhost:8080/.

Preview window (--preview / -p)

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

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

ℹ️ --preview option cannot use when you are using Marp CLI through official docker image.

Template

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

marp --template bespoke slide-deck.md

bespoke template (default)

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

Features

  • 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 unneccesary.
  • 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.
  • 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 Transitions API.

ℹ️ Presenter view may be disabled if the browser restricted using localStorage (e.g. Open HTML in the old Safari with private browsing, or open the local HTML file with Chrome that has blocked 3rd party cookies in chrome://settings/content/cookies).

Docs

bare template

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

Zero-JS slide deck

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

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

Metadata

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

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

*: If could not parse a specified value as valid, the URL will be ignored.

By global directives

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

---
title: Marp slide deck
description: An example slide deck created by Marp CLI
author: Yuki Hattori
keywords: marp,marp-cli,slide
url: https://marp.app/
image: https://marp.app/og-image.jpg
---

# Marp slide deck

By CLI option

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

Theme

Override theme

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

marp --theme gaia

Use custom theme

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

marp --theme custom-theme.css

ℹ️ Normally Marpit theme CSS requires @theme meta comment, but it's not required in this usage.

Theme set

--theme-set option has to specify theme set composed by multiple theme CSS files. The registed themes are usable in Marpit's theme directive.

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

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

Engine

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

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

Use Marpit framework

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

# Install Marpit framework
npm i @marp-team/marpit

# Specify engine to use Marpit
marp --engine @marp-team/marpit marpit-deck.md

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

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.

Confirm engine version

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

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

Use specific version of Marp Core

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

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

$ npm i @marp-team/marp-cli @marp-team/marp-core@^3.2.0 --save-dev
$ npx marp --version
@marp-team/marp-cli v2.x.x (w/ user-installed @marp-team/marp-core v3.2.0)

Configuration file

Marp CLI can be configured options with file, such as marp.config.js, marp.config.cjs, .marprc (JSON / YAML), and marp section of package.json. It is useful to configure settings for the whole of project.

// package.json
{
  "marp": {
    "inputDir": "./slides",
    "output": "./public",
    "themeSet": "./themes"
  }
}
# .marprc.yml
allowLocalFiles: true
options:
  looseYAML: false
  markdown:
    breaks: false
pdf: true

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

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

Options

Key Type CLI option Description
allowLocalFiles boolean --allow-local-files Allow to access local files from Markdown while converting PDF (NOT SECURE)
author string --author Define author of the slide deck
bespoke object
Setting options for bespoke template
┗ osc boolean --bespoke.osc [Bespoke] Use on-screen controller (true by default)
┗ progress boolean --bespoke.progress [Bespoke] Use progress bar (false by default)
┗ transition boolean --bespoke.transition [Bespoke] Use transitions (Only in browsers supported View Transitions API: true by default)
description string --description Define description of the slide deck
engine string | Class | Function --engine Specify Marpit based engine
html boolean | object --html Enable or disable HTML tags (Configuration file can pass the whitelist object if you are using Marp Core)
image png | jpeg --image Convert the first slide page into an image file
images png | jpeg --images Convert slide deck into multiple image files
imageScale number --image-scale The scale factor for rendered images (1 by default, or 2 for PPTX conversion)
inputDir string --input-dir -I The base directory to find markdown and theme CSS
jpegQuality number --jpeg-quality Setting JPEG image quality (85 by default)
keywords string | string[] --keywords Define keywords for the slide deck (Accepts comma-separated string and array of string)
lang string
Define the language of converted HTML
notes boolean --notes Convert slide deck notes into a text file
ogImage string --og-image Define Open Graph image URL
options object
The base options for the constructor of engine
output string --output -o Output file path (or directory when input-dir is passed)
pdf boolean --pdf Convert slide deck into PDF
pdfNotes boolean --pdf-notes Add presenter notes to PDF as annotations
pdfOutlines boolean | object --pdf-outlines Add outlines (bookmarks) to PDF
┗ pages boolean --pdf-outlines.pages Make PDF outlines from slide pages (true by default when pdfOutlines is enabled)
┗ headings boolean --pdf-outlines.headings Make PDF outlines from Markdown headings (true by default when pdfOutlines is enabled)
preview boolean --preview -p Open preview window
server boolean --server -s Enable server mode
template bare | bespoke --template Choose template (bespoke by default)
theme string --theme Override theme by name or CSS file
themeSet string | string[] --theme-set Path to additional theme CSS files
title string --title Define title of the slide deck
url string --url Define canonical URL
watch boolean --watch -w Watch input markdowns for changes

Advanced

The advanced options that cannot specify through CLI options can be configured by file.

Base options for engine constructor

options can set the base options for the constructor of the used engine. You can fine-tune constructor options for Marp Core / Marpit.

Example

The below configuration will set constructor option for Marp Core as specified:

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

⚠️ Some options may be overridden by used template.

 from https://github.com/marp-team/marp-cli

 

 

 

 

 

 

 

 

 

Posted by at
Labels:

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)