コマンドライン

slides [deck.md] [flags]
slides [command] [flags] deck.md

コマンド

slides <command> --help で、各コマンドのフラグを表示できます。フラグはスライドデッキの前にも 後にも置けます：slides deck.md -o out.html と slides -o out.html deck.md は同じです。長い形式のフラグはダッシュ 2 つ（--html）で指定します。短い形式は -o だけです。build は、-o で別の指定をしない限り、deck.md と同じ場所に deck.html を書き出します。

フラグ

複数のスライドデッキとディレクトリ

v0.6.0 では、build に複数のスライドデッキ、ディレクトリ（その下のスライドデッキを 再帰的に検索）、またはパターンを渡せます。最大 --parallel 個を同時にビルドします。 - は標準入力です。marp-cli と異なり、- を指定しない限りパイプは読み込みません。

パターンは marp-cli の glob と同じように解釈されます（** と {a,b} は v0.7.0 から。 シェルに展開させず slides に渡すよう、クォートしてください）。名前の中では *、?、[a-z]、 {md,txt} が使え、** は任意の数のディレクトリにマッチします。そのため 'docs/**/*.md' でツリー内のスライドデッキを指定できます。ワイルドカードはドットで始まる名前には マッチせず、node_modules の中は検索されず、大文字と小文字は区別されます （*.md では UPPER.MD は見つかりません）。パターンにマッチしたものは、拡張子にかかわらずすべて変換されます。 何にもマッチしないパターンはエラーになります。

• -I dir は、marp-cli と同じく dir 以下の Markdown ファイル（小文字の .md、.mdown、.markdown、 .markdn）を検索します。node_modules とドットで始まるディレクトリの中は検索しません。 -o out を指定すると、各スライドデッキは dir 以下のパスを out 以下に写した場所に書き出されます： dir/sub/b.md は out/sub/b.html になります（フラグに応じて b.pdf、b.001.png、b.txt、…）。 -o を指定しない場合、出力は各スライドデッキの隣に置かれます。-I と一緒にスライドデッキを 指定するとエラーになり、複数のスライドデッキに対する -o file もエラーです（-o - は使えます）。
• -P n は n 個のスライドデッキを同時にビルドします。1 つのスライドデッキのレンダリングでもすでに 複数のコアを使うため、n の上限はコア数です。-o - の場合は 1 つずつ順に ビルドします。各スライドデッキのメッセージはまとめて出力され、失敗したスライドデッキがあってもほかのビルドは 止まりません：終了ステータスは 1 になり、メッセージに失敗の一覧が表示されます。

トランジションと発表用ページ

v0.6.0 では、marp-cli の transition ディレクティブが使えます：<!-- transition: fade 1s --> のように名前と省略可能な継続時間を書くと、そのスライドと以降のスライドに適用され、 <!-- _transition: cover --> ならそのスライドだけに適用されます。組み込みの名前は marp-cli と同じです： clockwise、counterclockwise、cover、coverflow、cube、cylinder、 diamond、drop、explode、fade、fade-out、fall、flip、glow、 implode、in-out、iris-in、iris-out、melt、overlap、pivot、pull、 push、reveal、rotate、slide、star、swap、swipe、swoosh、wipe、 wiper、zoom。none でオフになります。ページは、閲覧者がトランジションの設定されたスライドから 次へ進むときと、そのスライドに戻ってくるときに、ブラウザーの View Transition API を使って再生します。 この API がないブラウザーでは従来どおりにスライドが切り替わり、 視差効果を減らす設定（reduced motion）を求める閲覧者には単純なフェードが使われます。テーマは独自の キーフレームを marp-transition-NAME（または marp-outgoing- と marp-incoming-、および -backward）という名前で提供でき、それらは組み込みのものより優先して使われます。

ページには 画面上のコントローラー（前へ、ページ番号、次へ、全画面表示）があります。 これはポインターが動いたりキーが押されたりすると表示され、少しすると隠れます （--bespoke.osc=false で削除できます）。また --bespoke.progress を指定すると、プログレス バーが表示されます。プログレスバーは現在デフォルトでオフです。 これは marp-cli と同じで、 以前は常に表示されていました。

発表者ビュー

v0.7.0 では、ページに marp-cli の発表者ビューがあります。p キーか、コントローラーの最後の ボタンを押すと、現在のスライド、その次のステップ、スピーカーノート、ページ番号、時刻、タイマーを 表示するウィンドウが開きます（タイマーをクリックするとリセットされ、+ と - でノートの文字サイズを変更でき、 スライドとノートの間のバーはドラッグできます）。2 つのウィンドウは双方向に連動します： どちらのウィンドウでも、矢印キー、次のステップのクリック、「前へ」/「次へ」のクリックで、 もう一方もフラグメント単位で移動します。

動作は marp-cli と同じで、その 4.5.1 のソースから読み取ったものです：ウィンドウは同じファイルの ?view=presenter&sync=KEY で、次のステップは同じページを ?view=next としてフレームに表示したものです。ウィンドウ間の位置は localStorage（bespoke-marp-sync-KEY）で共有されます。そのため、サーバーもネットワークも 不要ですが、localStorage がないブラウザーでは動作しません（ボタンにその旨が表示されます）。 ノートはテキストとして扱われ、&、<、> はエスケープされるので、ノートがマークアップになることはありません。 ノートは発表者ビューが取り出せるよう、非表示の状態でページに含まれています。これにより、スクリーンリーダーが 聴衆向けに読み上げる内容にはノートが含まれません。 --bare のページにはこの機能はありません。発表者ビューによってページのサイズは約 10 KB 増えます。

一覧表示

v0.8.0 では、o キー（または Escape。marp-cli はどちらでも切り替わります）、 コントローラーのグリッドボタン、または発表者ビューのページカウンターを押すと、すべてのスライドが ページの上にグリッド状に全体表示されます。矢印キーでスライドを選び（上下キーは行単位で移動）、 Home と End で先頭と末尾に移動でき、ほかのウィンドウも連動します。 Enter、Space、またはクリックでスライドを選択すると、ページ上の一覧表示の場合は一覧表示が閉じます。 発表者ビュー上では、選択しても一覧表示は開いたままです（発表者は表示するスライドを選んだ後も、 一覧を見続けられます）。「Close overview」ボタン、o、 Escape で閉じます。これは marp-cli と同じ仕組みです：同じページを ?view=overview&sync=KEY でフレームに表示し、位置を localStorage で共有するので、 ネットワークは不要です。グリッド内のスライドはフォーカス可能で「Slide N」というラベルが付き、 閉じた一覧表示は inert になるので、キーボードやスクリーンリーダーの利用者が誤ってそこに入り込むことは ありません。発表者ビューと一覧表示を合わせて、ページのサイズは約 15 KB 増えます。

設定ファイル

marp-cli は作業ディレクトリにあるファイルからオプションを読み込みます。slides も、そのファイルが データであれば同じように読み込みます：.marprc（YAML。JSON も YAML として読めます）、 .marprc.json、.marprc.yaml、.marprc.yml、.config/marprc*、または package.json の marp キーです。--config-file（-c）では任意の JSON または YAML ファイル（たとえば marp.config.json）を指定できます。marp-cli の検索と同じく、検索するのは 作業ディレクトリだけで、親ディレクトリは検索しません。JavaScript や TypeScript のファイル （marp.config.js …）はプログラムなので slides は実行しません。その旨を表示して 処理を続けます。使えるオプションは、marp-cli のドキュメントにあるもののうち go-slides で意味を持つものです：title、description、author、keywords、url、ogImage、lang、 theme、themeSet、html、allowLocalFiles、template、bespoke、 inputDir、output、parallel、pdf、pptx、notes、pdfNotes、 pdfOutlines、images、image、imageScale、jpegQuality、watch、 server、preview。パスはそのファイルからの相対パスです。コマンドラインの指定が優先されます。 engine、options、browser* は Marp のエンジンとブラウザーを必要とするため、 --browser* フラグと同じく警告を出して無視されます。そのため、marp-cli 向けに書いたスクリプトは そのまま動作します（slides.yaml と slides.hcl、およびそこに書く kind と テンプレートのデータは別物で、従来どおりに読み込まれます）。

監視、配信、プレビュー

v0.6.0 で導入され、marp-cli のルートとライブリロードのプロトコルに対応しています（その 4.5.1 のソースから読み取り、実行中の marp -s と比較しました）。

slides --server dir（-s）は、ディレクトリを http://127.0.0.1:8080/ で配信します （ポートは環境変数 PORT で変更できます。すでに使用中のポートを指定すると、 その旨を示すエラーになります）。

ページは /.__marp-cli-watch-notifier__/<id> への WebSocket を開きます。id は スライドデッキのパスの SHA-256 です。サーバーは ready を送り、スライドデッキまたはディレクトリ以下の 何かが変更されると reload を送ります。末尾のスラッシュなしでリクエストされたディレクトリは、 スラッシュ付きの URL にリダイレクトされます（marp-cli はスラッシュなしでも一覧を返すため、 ページの相対リンクが壊れます）。

--watch（-w）はスライドデッキをビルドした後、変更されたスライドデッキを再ビルドします。 --theme-set のファイル、kind やデータのファイル、または設定が変更された場合は、すべてを再ビルドします。 書き出されたページはループバック上のソケット（ポート 37717、または次の空きポート）を開き、自分のスライドデッキが再ビルドされると再読み込みされます。 ビルドに失敗したスライドデッキはエラーが報告され、引き続き監視されます。--preview（-p）は、 デフォルトのブラウザーでサーバー、または直前にビルドした HTML ページを開きます。slides には 操作するブラウザーがないため、独自のウィンドウは持ちません。

サーバーはマシンへの入り口になるので、すべてのインターフェースで待ち受けて何もチェックしない marp-cli のサーバーよりも厳しくしています。

• 127.0.0.1 で待ち受けます。--host で変更できますが警告が出ます。また、ワイルドカードアドレスでは Host ヘッダーをチェックできなくなります。
• Host ヘッダーは、ループバックの名前（localhost、127.0.0.1、 [::1]、*.localhost）か、待ち受けているホストでなければなりません。これにより DNS リバインディングを防ぎます。
• WebSocket の Origin は、サーバー自身のものでなければなりません。監視モードのソケットは、 ファイルから開いたページの null オリジンも受け付けます。ほかのサイトからのリクエストのうち、 ナビゲーション以外のもの（スクリプト、画像、fetch）は拒否されます。
• パスは正規化され、シンボリックリンクは解決され、その結果がディレクトリ内になければなりません： .. やディレクトリ外へのリンクは拒否され、外部にあるスライドデッキの ?pdf も拒否されます。 ドットで始まる名前（.git、.env）は配信されません。
• 受け付けるのは GET と HEAD だけです。同時に行う変換は少数に限られ、監視するディレクトリは 最大 4096 個で、node_modules の中やドットで始まるディレクトリ以下は監視しません。

ページのメタデータ

marp-cli と同じく、コマンドラインの指定がスライドデッキより優先されます。marp-cli では、フラグは 最後のディレクティブコメントとしてスライドデッキに追加されます。以下のルールは marp-cli 4.5.1 から読み取り、その出力と照らし合わせるテストで固定しています（v0.6.0）。

• title を指定していないスライドデッキでは、最も上位のレベルの最初の見出しのテキストが、 書いたとおりに使われます（# **Bold** title なら **Bold** title）。見出しがなければ <title> はありません。
• keywords はカンマで分割され、前後の空白が除かれ、重複が取り除かれます。フロントマターのリストは そのまま使われます。marp-cli と同じく、ページに keywords タグが付くのはキーワードが 2 つ以上の 場合で、1 つだけのときは付きません。
• 無効な url（絶対 URL でないもの）は警告を出して無視され、前の値が保持されます。有効な ものは <link rel="canonical"> と og:url も書き出します。
• author と description には、対応する Open Graph のタグも付きます。og:image:alt と大きな Twitter カードには、タイトルと画像の両方が必要です。

画像、PDF、PPTX、ODP

marp-cli と同じく、-o に .pdf、.pptx、.odp、.png、.jpg の拡張子を付けると、 それによって形式が選ばれます。出力ディレクトリは自動的に作成されます。PDF はスライドごとに スライドと同じサイズのページが 1 枚あり、スライドとその見出しのアウトラインが付きます。

PDF のノートとアウトライン

v0.6.0 では、PDF は marp-cli の 2 つのオプションに対応しています。同じスライドデッキについて marp-cli 4.5.1 が書き出す PDF と比較しています。

• --pdf-notes は、各スライドのスピーカーノートを、そのページにノート注釈として追加します。 左下に黄色いノートアイコンが表示され、その内容はノート（複数のコメントは空行で連結）、 タイトルはスライドデッキの author です。marp-cli と同じく、--pdf-notes だけを指定すると PDF を書き出します。
• アウトラインには、スライドごとの太字のしおり「Page N」と、その下にレベル別に入れ子になった スライドの見出しが含まれます（--pdf-outlines.pages と --pdf-outlines.headings でそれぞれを選択します）。アウトラインは、ここではデフォルトで オン、marp-cli ではオフです。 slides は以前から常にアウトラインを書き出してきました。数百 バイトしか増えず、長いスライドデッキでも移動しやすくなるので、このデフォルトを維持しています。 --pdf-outlines=false または marp-cli の --no-pdf-outlines でオフにでき、 .pages や .headings に =false を付けるとその部分だけを省きます。見出しのしおりは そのスライドに移動します。marp-cli ではさらに見出しの位置までスクロールします。

レンダリングは go-webengine が行い、 PDF は go-pdfkit が書き出します。 組み込みテーマが使うフォント（Lato、Roboto Mono）は go-opentype/fonts から取得して埋め込まれるので、 レンダリング中にネットワークにアクセスすることはありません。Chrome は使いません。

--image-scale 2 は、CSS ピクセルあたり 2 デバイスピクセルでレンダリングします。ローカルの画像は --allow-local-files を指定しない限り拒否され、指定した場合でも、スライドデッキのディレクトリ以下にある ファイルしか読み込みません：外部から来たスライドデッキが ~/.ssh にアクセスすることはできません。 複数の背景や分割背景（![bg left:40%]）は、Marp のレイヤーと同じようにレンダリングされます。

--pptx は、go-ooxml の WritePresentation を使って、スピーカーノートとスライドデッキのメタデータ付きでスライドデッキを書き出します。 v0.5.0 以降、スライドは編集可能です（後述）。--pptx-raster は、marp-cli と同じくスライドごとに スライド全面の画像を 1 枚書き出します。倍率のデフォルトは 2 で、 --image-scale で上書きできます。結果は LibreOffice で開けます。テストしたのは LibreOffice だけで、PowerPoint と Keynote ではテストしていません。

--odp は、go-odf の WritePresentation を使って、スピーカーノート付きの OpenDocument プレゼンテーションを書き出します。 --odp-raster はスライドごとに 1 枚の画像を書き出します。

編集可能な PPTX と ODP

v0.5.0 以降、PPTX や ODP のスライドは 編集可能 です。marp-cli の PPTX はスライドごとに 1 枚の画像で、実験的な --pptx-editable は PDF を LibreOffice で変換するものです。go-slides では、各スライドを PNG や PDF のエクスポートで 使うのと同じレイアウトから描画します。

• テキストの各行は、レイアウトされた位置に置かれたテキストボックスで、スライドのレイアウトに使われた フォントで表示されます。フォントは ファイルに埋め込まれる ので、Lato や Inter がないマシンでも 同じ見た目になります（LibreOffice 25.8 で確認）。太字、斜体、色、文字間隔、クリック可能なリンクも 保持されます。
• 背景、枠線、角丸のボックスは図形になります。グラデーションは、PPTX ではグラデーション塗りつぶし、 ODP では画像になります（ODF のグラデーションは 2 色までのため）。
• 画像は、何枚のスライドに表示されていても 1 回だけ格納されます。
• スライドで表現できないもの（opacity の下にある要素、filter、 ぼかしのある影、数式）は、その要素の画像になり、テキストはその上に 保持されます。

LibreOffice でレンダリングし直すと、スライドは PNG エクスポートのピクセルとの差が 0.04〜2 % に収まります。 --pptx-raster と --odp-raster では、スライドごとに 1 枚の画像のままです。

ベクター PDF

v0.4.0 以降、PDF はベクターで描画されます：go-webengine は、レイアウトされた スライドをピクセルではなく PDF に描画します。テキストはテキストのままで、スライドのレイアウトに使われた フォントが /ToUnicode マップ付きでサブセット埋め込みされるため、選択、検索、コピーができます。 背景、枠線、グラデーションはパスとシェーディングになり、多くのスライドに表示される画像は 1 回だけ 埋め込まれ、リンクはクリックできます。100 枚のベンチマーク用スライドデッキは 758 KiB で、 marp-cli の 837 KiB、v0.3.0 の画像 PDF の 10 MiB と比べて小さく、0.3 s で書き出されます。

ここでベクターで表現できない要素（opacity < 1 の下にあるもの、filter や回転があるもの、ぼかしのある box-shadow、不透明度がフェードするグラデーション）は、 その要素だけをビットマップとして描画し、テキストは選択できるように、その上に透明なまま重ねます。 数式は現在もビットマップです。--pdf-raster は、v0.3.0 と同じくページごとに 1 枚の画像を 書き出します。

slides.yaml

スライドデッキと同じ場所にある設定ファイルはそのスライドデッキに適用されるので、フォルダー内の スライドデッキで 1 つの設定ファイルを共有できます。

kinds: kinds.yaml        # a mapping of kinds, or file(s) holding one
themes:                  # theme CSS files or directories
  - themes/
data:                    # template data
  company: Example Inc.
html: false              # allow all raw HTML
lang: en

kind について：スライドデッキ自体の kinds: が、設定ファイルとコマンドラインの指定より優先されます。 データについて：設定ファイルとコマンドラインの data が、スライドデッキのフロントマターより 優先されます。そのため、1 つのスライドデッキを異なるデータでビルドできます。

予定

まだ実装されていないもの：PDF 内の数式のベクター化。実装されたら、ここにコマンドまたはフラグとして 記載します。