エムスリーテックブログ

エムスリー(m3)のエンジニア・開発メンバーによる技術ブログです

Marp CLI (Marp Next) をとりあえず知る・使い始めるためのまとめ記事

Marp

Marp は markdown 形式でプレゼンテーションを作成できるソフトウエアです。Markdown で記述したスライドをブラウザ上で描画したり PDF に出力したりできます。

その性質上、万人向けのツールではないところがあります *1。しかし、以下のようなニーズに対してはとても素晴らしいツールだと思います:

  • WYSIWYG エディタにマウスで格闘するより、テキストエディタを使いたい
  • Git と相性の良い、テキストベースのフォーマットで書きたい
  • 一つの markdown のファイルからプレゼンテーションもドキュメントも生成したい

筆者は既に社内外や個人で複数のスライドを Marp で作成しており、非常に便利なツールで助かっています。

実際に 私が Speaker Deck で公開しているスライド は 2018 年以降 Marp で全て作成しています。数百名の方向けの登壇発表などでも特に不自由もなく利用できています。

このように便利なツールなのですが、Marp Next (Marp CLI) を使い始めるまでの手順がまとまった資料があまりなかったため、分かる範囲でまとめてみました。

この記事の想定読者レベル

  • markdown 記法に抵抗がない
  • フロントエンド系の開発環境や node.js に詳しくはないが、コマンドライン環境の基本的な操作はできる
    • フロントエンドに詳しい方は @marp-team/marp-cli の README 等を見ながら好きな方法でセットアップすればよいと思います
    • 本稿では node.js 等に詳しくない読者を想定して書いています (Marp の布教のために)

Marp Next (Marp CLI) と旧 Marp について

Marp には旧・初代 Marp と、次世代の Marp (Marp Next, Marp CLI, Marp Core)があり、両者は互換性のない別実装です。

詳しくは Marp の作者の方の Qiita 記事 に書かれていますが、要するに

  • 旧 "Marp" : デスクトップアプリケーション (開発停止)
  • Marp Next (Marp CLI, Marp Core) : 新規に作られた実装

のようです。

検索して出てくる情報は旧 Marp が多いので、注意して読んだほうが良いです。

旧 Marp についてはすでに情報が多くある & 開発停止しているので、ここでは Marp Next にフォーカスします。

Marp Next のインタフェースについて

https://github.com/marp-team/marp によると、以下のインタフェースがあるようです:

  • Marp CLI : コマンドラインツール (2019/05 時点で ver 0.9.2)
  • Marp Web : PWA 形式の web アプリ (2019/05 時点では demo 段階)
  • Marp Desktop : 旧 Marp と同じくデスクトップアプリケーション。まだ無い。

現時点では Marp CLI が実質上唯一の選択肢です。CLI という名前ですが、筆者の感覚としてはスライド作成に十分な機能が備わっています (後述)。

Marp CLI を使う流れ

色々なやりかたが可能ですが、こだわりが無ければ以下のような流れが良いと思います:

  1. node.js をインストールしていないならば、最新の node.js をインストールする (yarn コマンドもセットで入る)
  2. ディレクトリを作成し、後述のような package.json ファイルを作成する
  3. yarn install コマンドを実行し、package.json で指定したバージョンの Marp CLI をインストールする
  4. Marp CLI を使って、ブラウザでプレビューしたり PDF 生成したりする (後述)

marp-cli の README では npx コマンドで起動できるともありますが、実際は上記の方が実用的です *2。

Marp CLI のための package.json

package.json は JavaScript のプロジェクト定義ファイルのようなものです。といって、Marp CLI を使う目的では以下のような記述で十分です:

{
  "name": "my-slide",
  "version": "1.0.0",
  "main": "index.js",
  "author": "作者名",
  "license": "UNLICENSED",
  "private": true,
  "scripts": {
    "dev": "marp --html --server .",
    "build": "marp --html --pdf --allow-local-files --title 'スライドのタイトル' slide.md -o ./slide.pdf"
  },
  "dependencies": {
    "@marp-team/marp-cli": "^0.7.0"
  }
}

もしソースを公開する予定があるならば license 部分は見直してください。

上記の package.json で今回の用途で重要なのは以下の 2 点だけです:

  • dependencies の @marp-team/marp-cli
    • 上記の例では 0.7.0 ですが、https://www.npmjs.com/package/@marp-team/marp-cli にある最新バージョンを使うのがよいでしょう
    • ^0.7.1 と書いた場合、0.8 未満かつ 0.7.1 以上のバージョンが使われます
  • scripts にあるコマンドの記述
    • これらは yarn dev, yarn build などとして呼び出すことができます
    • 中身は shell script です (リダイレクトなども使えます), ただし dependencies で指定した marp コマンドにパスが通った状態で使えます

yarn install で Marp CLI をインストール

yarn install (または単に yarn) コマンドを実行すると、 dependencies で指定したものがインストールされます。つまり Marp CLI がインストールされます。

ただし、システム全体にインストールされるのではなく、 package.json と同じディレクトリに node_modules というディレクトリが作成され、その下にインストールされます。それによって以下のようなメリットがあります:

  • プレゼンテーションごとに異なるバージョンの marp (や marp の依存ライブラリ)を利用できる
    • Marp やそれが依存する JavaScript ライブラリは開発が活発ですし、過去に作ったスライドを最新版で開いたら変なことに...という事態を回避する意味で重要です
  • package.json と同じ階層の node_modules 以下に配置されるだけなので、管理者権限が不要 & システムの環境が汚れる心配もない

Git を使う場合、 node_modules/ は .gitignore に指定した方が良いです。

スライドを markdown で作成

Marp Next のスライドは例えば以下のようになります:

---
theme: default
paginate: true
footer: スライドのフッター
---

## Marp Next プレゼンテーション

---

# スライドのタイトル

本文
本文

---

## スライドのタイトル

- もちろん箇条書きもできる
- 箇条書き
- 絵文字も使える :+1:

--- でページ区切りする以外は、ほぼ普通の Markdown ではないでしょうか。

先頭にある theme などを指定している部分は Directive という機能で、スライドの全ページを制御しています。<!-- _paginate: false --> などとすることでスライドごとに制御することも出来ます。

詳細な仕様は今後のバージョンアップ等で変わる可能性があるので深く触れないですが、 marp-team/marpit のドキュメントを参照すると良いでしょう。

スライドをプレビュー

Marp CLI には web サーバーとして動作する機能があり、その web サーバーにアクセスすることでブラウザで閲覧することができます。Markdown そのものではなく、聴衆に見せるためのスライドの状態で見えるため、プレビュー機能として使えます。

  "scripts": {
    "dev": "marp --html --server ."
  }

package.json の上記の記述があれば、 yarn dev コマンドによって marp を --server モードで起動できます。うまくいけば http://localhost:8080/ が利用可能である旨のメッセージが出ると思います。

その URL にブラウザでアクセスすることで、スライドを閲覧することができます。

この機能の優れている点として、markdown を上書き保存すると自動で再読込みされ、しかもブラウザ側も自動でリロードされます。なので、スライドを編集する際はこの機能を使うと便利でしょう。

なお、package.json の記述にある --html オプションは無くても良いですが、その場合は Markdown 中に HTML を埋め込むことができないので、細かな書式制御などは困難になります。

スライドを PDF に変換

  "scripts": {
    "build": "marp --html --pdf --allow-local-files --title 'スライドのタイトル' slide.md -o ./slide.pdf"
  }

package.json の上記の記述があれば、 yarn build コマンドによって slide.md (先程書いた markdown のファイル名)が読み込まれ、slide.pdf が出力されます。あとは全画面表示に対応する PDF ビューワーを使うことでプレゼンできます。

留意点として、 --allow-local-files オプションを付与しないかぎり画像などの外部ファイルを markdown から参照できません。自分で書いている(スライドに出してはいけないファイルを読み込んだりはしていないと信用できる)スライドを扱うならば --allow-local-files オプションは付けておいたほうが良いでしょう。

なお、 yarn marp --help コマンドで marp コマンドの help を参照できます。他に利用可能なオプションなどはそちらを参照してください。

アスペクト比 4:3 のプロジェクタへの対応

Marp CLI には いくつかのテーマが built-in で入っている のですが、いずれもサイズが 16:9 比になっています。スライドの縦横比はテーマごとに決まっている仕様なので、このままですと 4:3 のプロジェクタの環境では困ったことになります。今でも貸し会議室などの設備によっては 4:3 のことがあるので...。

そこで 4:3 に対応するテーマを使うことになるのですが、実は以下のようにすると簡単に対応できます。

まず、Marp の built-in テーマを拡張するテーマの定義 CSS を書きます:

@import-theme 'default';

section {
    /* section 要素が各スライドのルート要素であり、この要素のサイズを調整することでスライドの大きさを調整できる */
    width: 1024px;
    height: 768px;
}

@import-theme というのは Marp 固有の記法で、これによって Marp が認識しているテーマを import できます (ここでは default テーマを import している)。

そして、marp コマンドの引数に --theme theme.css などと指定して上記の CSS を読み込ませることで、指定したとおりのサイズのスライドで出力されるようになります。

　

この点以外ではハマりどころは無かったのですが、もし思い出したら適宜記載します。

Enjoy markdown life

このように、markdown やコマンドラインにさえ抵抗がなければ、Marp は便利に使えるプレゼンテーションツールです。ぜひ使ってみてはいかがでしょうか。

We are hiring!!!

弊社エムスリーはインターネット技術を用いて医療に関わるコストを少しでも減らし、より多くの人を健康にすることがミッションです。なのでスライドの作成のようなタスクであっても、エンジニアリングの工夫によって生産性を向上することは歓迎です (とはいえ、もちろん PowerPoint / Keynote 派の方も多くおります)。この記事（or 他の記事も）を読んで興味を持った方はぜひ下記リンクよりご応募ください！

m3.recruitment.jp

*1:Slack ですら「大多数のユーザーのニーズに対応する」ために Markdown 記法をあえて採用していないぐらいです: https://get.slack.help/hc/ja/articles/202288908

*2:主な理由: npx で毎回起動すると遅い点, dependencies でのバージョン指定はしておいたほうが良い点, package.json の scripts にコマンドを記述しておいたほうがシンプルである点