- 元ネタ: https://bookdown.org/yihui/rmarkdown/xaringan-start.html
- 順序とかはチョット変えました
- ライセンス: CC BY-NC-SA 4.0
1 はじめに
xaringanはJavaScriptライブラリのremark.js (https://remarkjs.com)を用いてHTML5のプレゼンテーションを作成するRのパッケージです。xaringanを使うとこんな感じのスライドが作成できます。
このパッケージの名前は「ナルト」の写輪眼から来ています。これは発音のしづらさと、作者が非常に気に入っているこのスタイルが「有名になりすぎる」のを懸念したため採用されたそうです（昨今の学会はLaTeX Beamerを使ったスライドばかりなので、作者はBeamerの使用をやめたそうです）。そんな心配をよそに、xaringanは非常に柔軟なカスタマイズが可能であるため、現在ではユーザーが作成した独自のスタイルもコントリビュートされるようになっています。
remark.jsはMarkdownしかサポートしませんが、xaringanはR Markdownのサポートを追加し、さらにスライドの作成とプレビューを容易にするいくつかのツールも付け加えました。
パッケージにまつわる背景や、使い方についてもう少し詳しく知りたければ、xaringanによって作成されたスライドであるPresentation Ninjaを見てみると良いでしょう。また、作者がなぜxaringan/remark.jsを用いたHTML5プレゼンテーションにこだわるかを知りたければ作者のブログ記事Why xaringan / remark.js for HTML5 Presentations? - Yihui Xie | 谢益辉を読んでみるのも良いかもしれません。
2 パッケージのインストール
では早速パッケージをインストールしてみましょう。xaringanはCRANから取得できます。
# CRANからインストールするならこちら
install.packages("xaringan")
# GitHubから開発版をインストールするならこちら
# devtools::install_github("yihui/xaringan")
パッケージをインストールすると、File > New File > R Markdown > From Templeteの中にNinja Presentationが出現します。これを選択するとxaringanパッケージを使ったスライドをテンプレートから作り始めることができます。まずはこれを選択してそのままknitしてみると良いでしょう。
このパッケージによるR Markdownの出力フォーマットはmoon_reader()で定義されています。したがって、可能な設定のすべては、?xaringan::moon_readerから確認できます。
以下はxaringanパッケージによるスライドを生成する.Rmdファイルの簡単な例です。
---
title: "スライドタイトル"
subtitle: "スライドサブタイトル"
author: "氏名"
date: "日付"
output:
xaringan::moon_reader:
lib_dir: libs
nature:
highlightStyle: github
countIncrementalSlides: false
---
一枚目のスライド。
---
二枚目のスライド。
3 スライドのフォーマット
スライドを作成していく前に、remark.jsやxaringan、Pandocの関係について簡単に説明しておきます。
remark.jsのWikiには、スライドの見栄えを調整するための詳細なドキュメントが整備されていますが、remerk.jsに比べると、xaringanはいくつかの点で単純化を行っています。例えば、ユーザーはboilerplate HTMLを準備する必要はありませんし、自動再生はmoon_reader()のオプションを通じて設定できますし、LaTeX形式の数式もきちんとレンダリングされます。
remark.jsのMarkdown解釈は、PandocのMarkdownと互換性が無いという点に注意して下さい。つまり、PandocのMarkdownの先進的な機能の中には使えないものがあります（例えば相互参照のための記法である[@key]が使えません）。
もしremark.jsがサポートしてない機能を使用したければ、生のHTMLを記述することもできます。例えば、HTMLテーブルをknitr::kable(head(iris), 'html')のように生成して利用することができます。
3.1 スライドとプロパティ
スライドとスライドの区切りは3つの連続したダッシュ（---）で指定します。スライドのコンテンツには好きなものを含めることができます。つまり、タイトルは無くても構いませんし、逆に任意のレベルのタイトルをいくつでも含めることができます。
スライドにはプロパティを設定できます。プロパティにはclassやbackground-imageのようなものが含まれ、それぞれのスライドの最初に記述します。例を示します。
---
class: center, inverse
background-image: url("images/cool.png")
# 新しいスライド
スライドの中身
classプロパティはスライドを囲むHTMLタグにクラスを設定します。これはCSSを使ってスライドの外観を調整したい場合に利用することができます。例えば、クラスinverseに次のようなCSSを設定しておけば、暗い背景に明るい文字色のスライドに変更できます。
.inverse {
background-color: #272822;
color: #d6d6d6;
text-shadow: 0 0 20px #333;
}
これを記述するCSSファイルは、xaringan::moon_reader以下のcssオプションで指定できます。
---
output:
xaringan::moon_reader:
css: "my-style.css"
---
ところで、実はinverseというクラスはxaringanのデフォルトテーマ内で既に定義してあります。したがって、デフォルトのテーマを上書きしたいのでなければ、わざわざcssを書かずとも色調を反転したスタイルで表示されます（実際、タイトルスライドにはinverseがデフォルトで設定されています）。
background-imageプロパティを利用すると、スライドの背景画像を設定できます。画像はローカルのものでもオンラインのものでも構いませんが、パスはurl()の内部に記述する必要があります。背景画像はcssの記法を使ってサイズや位置を調整することもできます
background-image: url("https://github.com/yihui/xaringan/releases/download/v0.0.2/karl-moustache.jpg")
background-position: center
background-size: contain
すべてのプロパティを理解するにはCSSの知識が必要です。
ところで上記の例では、実はインラインで式xaringan:::karlを展開してKarl Bromanの画像URLを埋め込んでいます。これはxaringanパッケージの有用な機能の一つです。
3.2 タイトルスライド
タイトルスライドはYAMLメタデータから自動的に生成される特別なスライドです。タイトルスライドにはタイトル、サブタイトル、著者、日付を含むことができますが、これらはすべて任意の項目です。このスライドにはinverse、center、middle、title-slideという4つのクラスがデフォルトで設定されます。このスタイルが望ましくなければ、.title-slideクラスをカスタマイズするか、YAMLのnatureオプション以下でtitleSlideClassオプションを通じて任意のクラスを設定することもできます。
---
output:
xaringan::moon_reader:
nature:
titleSlideClass: ["right", "top", "my-title"]
---
タイトルスライドの生成自体を抑制したければ、sealオプションにfalseを指定します。
---
output:
xaringan::moon_reader:
seal: false
---
class: inverse
# 独自タイトル
### 独自著者
3.3 コンテンツクラス
スライドと同様に、スライド内の任意の要素に対しても.className[content]といった構文を使うことで好きなクラスを設定することができます。これをコンテンツクラスと称します。
コンテンツクラスはremark.jsの強力な機能の一つであり、Pandocで実現できない数少ない機能の一つでもあります。基本的には、これによってスライド内のどのような要素であってもCSSによってスタイルを設定することができます。
コンテンツクラスとしての利用に便利な組み込みのクラスも用意されています。例えば.left[ ]、.center[ ]、.right[ ]を利用すると、要素の水平位置を制御できます。画像をセンタリングしたければ次のようにできるわけです。
.center[]
[ ]内のコンテンツはパラグラフやリストなど、なんでも構いません。
xaringanのデフォルトテーマに含まれるクラスをもう少し紹介します。
-
.left-column[ ]および.right-column[ ]はサイドバーレイアウトの作成に使えます。左のサイドバーはスライドの20%の幅で、右のカラムは75%の幅となっています。 -
.pull-left[ ]および.pull-right[ ]は2カラムレイアウトの作成に使えます。2つのカラムは同じ幅で配置されます。
CSSについて知識があれば、自分でコンテンツクラスを定義することもできます。例えば次のようにCSSで定義しておけば、.red[ ]でコンテンツ内のテキスト色を赤にすることができます。
.red{ color: red; }
3.4 スライドのコンテンツを順次表示する
スライドのコンテンツを順次表示したいような場合は、コンテンツを--で区切ります。--はコンテンツクラスの内部でなければ、どこでも指定できます。
3.5 プレゼンターノート
プレゼンターモード（スライド表示中にpを押すと切り替わります）でのみ表示されるノートをスライドに追加することができます。ノートは???に続いて記入します。???以下の部分でもMarkdownは有効です。つまり、文字の装飾やリスト、画像など、Markdownで記述できるものならなんでも書けます。
スライドに多くの文章を詰め込んでしまう、というのはプレゼンテーションに不慣れな人間が犯しがちなミスです。スライド内の視覚的要素は簡潔に、不足する部分は言葉で補いましょう。もし話す内容を全て覚えていられないというのであれば、ノートの利用を検討してみて下さい。
remark.jsのプレゼンターモードは非常に強力で、市販のプレゼンテーションソフトのように発表者用の画面と映写用の画面を同期して別々に表示することもできます。そのためには次のように操作します。前提として、PCがプロジェクタに接続されているものとします。
- PCとプロジェクタのディスプレイがミラーリングしないように設定する。
- macOSであれば、「システム環境設定 > ディスプレイ >
配置」で「ディスプレイをミラーリング」のチェックボックスをOFFにします。
- スライドをブラウザで表示し、
cをタイプ。
- スライドが他のウィンドウ（あるいはタブ）に複製されます。このスライドは複製元のスライドとページが同期します。
- 複製されたスライドの片方をPCのディスプレイ、もう片方をプロジェクタに移動する。
- PC側のスライドをプレゼンターモードにする（
pをタイプ） - プロジェクタ側のスライドをフルスクリーンにする（
fをタイプ）
3.6 キーボードショートカット
上述のプレゼンターモード切り替え以外にもプレゼンテーションの最中に使えるキーボードショートカットがいくつかあります。キーボードショートカットの一覧は、スライド表示中にh（Helpの頭文字）または?をタイプすると確認できます。
3.7 yoloモード
有効にするとKarl Bromanの画像がランダムにスライドに紛れ込むステキ機能！
画像を好きなものに変更したり、紛れ込み枚数を変更することもできる！
4 スライドのビルドとプレビュー
.Rmdファイルを編集する度にknitを繰り返すのは面倒です。アドインのInfinite Moon Readerを使うと、.Rmdファイルが更新される度にプレビューも更新されるようになります。アドインを使う代わりに関数xaringan::inf_mr()を実行しても構いません。このプレビューはservrパッケージにより起動されたローカルWebサーバーにより実現されています。
xaringan::moon_readerの出力を他の種類のR Markdownの出力フォーマットと比較した場合の違いとして、デフォルトではself-containedなHTMLが出力されないという点が挙げられます。つまり、画像やJavaScriptライブラリはHTMLファイルに埋め込まれないということです。
これはremark.jsがPandocを使用せず、Markdownをリアルタイムにレンダリングしているという技術的な理由によります。そのため、self-containedなHTMLを生成するのは困難です。スライドをWebサイトに公開する必要があるが、依存関係のすべてをアップロードすることが難しいという場合には、xaringanは良い選択肢では無いかもしれません。GitHub PagesやNetlifyを使う場合はこれは問題になりません。すべてのファイルをコミットするかアップロードすれば良いのです。
5 CSSとテーマ
既に説明しましたが、CSSファイルはcssオプションから指定します。複数のファイルを指定したければパスをベクトルで与えます。
---
output:
xaringan::moon_reader:
css: ["default", "extra.css"]
---
基本的には、ファイルパスは拡張子を含む必要があります。パスに拡張子が含まれていない場合は、xaringanの組み込みCSSだとみなされます。上記のdefaultがその例です。これは、パッケージに組み込みのdefault.cssを指します。このCSSが保存されている場所はxaringan:::pkg_resource()で確認できます。組み込みCSSの一覧は、xaringan:::list_css()で確認できます。
デフォルトCSSの一部を変更したいという場合は、default.cssをコピーするのではなく、新しいCSSファイルを作成してそこで指定するようにしてください。その方が一般的にファイルサイズも小さくできます。
パッケージにはユーザーが投稿したテーマもいくつか含まれています。metropolisもその一例です。
---
output:
xaringan::moon_reader:
css: [default, metropolis, metropolis-fonts]
---
すべてのテーマはxaringan::list_css()で取得できる一覧のnames属性を取得することで確認できます。
names(xaringan:::list_css())
## [1] "default-fonts" "default" "duke-blue"
## [4] "hygge-duke" "hygge" "metropolis-fonts"
## [7] "metropolis" "middlebury-fonts" "middlebury"
## [10] "rladies-fonts" "rladies" "robot-fonts"
## [13] "robot" "rutgers-fonts" "rutgers"
## [16] "tamu-fonts" "tamu" "uo-fonts"
## [19] "uo"
テーマにコントリビュートしたい場合は、次のガイドも確認して下さい。
6 tips
6.1 自動再生
nature以下でautoplayオプションに時間を指定することで自動再生ができます。指定する時間の単位はミリ秒です。
6.2 カウントダウンタイマー
nature以下でcountdownオプションに時間を指定することでカウントダウンタイマーをすべてのスライドに表示できます。時間が来てもスライドは切り替わりませんが、タイマーが赤色になって超過時間を示すようになります。
6.3 コードラインのハイライト
nature以下でhighlightLines: trueの指定をすると、コードブロック中で*から始まる行、{{ }}で囲まれた行、#<<というコメントがついた行はコードブロック中でハイライトされます。*は正しいR構文とはなりませんが、後者2つは追加してもRの構文として特に問題がない、という点にも注目して下さい。
6.4 オフラインへの対応
デフォルトではxaringanはremark.jsのオンライン版を利用します。したがって、スライドをオフラインで使用するつもりであれば、事前にremark.jsをダウンロードしておく必要があります。xaringan::summon_remark()を使用すると、最新版、あるいは任意のバージョンのremark.jsをダウンロードして保存することができます。デフォルトでは、libs/remark-latest.min.jsに保存されます。保存したファイルはchakraオプションで読み込みの指定をします。
---
output:
xaringan::moon_reader:
chakra: libs/remark-latest.min.js
---
他の依存関係次第では、スライドを完全にオフライン対応することは難しいかもしれません。remark.js自体は単一ファイルから構成されているのでそれほど難しくありませんが、例えばMathJaxは非常にトリッキーです。また、Googleのwebフォントを使用している場合は、これもオフラインでは動作しません。Herokuアプリであるgoogle webfonts helperはフォントのダウンロードと必要なCSSの生成を助けてくれるでしょう。
6.5 マクロ
remark.jsのMarkdowシンタックスは驚くべき拡張性があります。ユーザー定義のマクロ（JavaScriptの関数です）を定義することができ、![:macroName arg1, arg2, ...]やのような構文で利用できるのです。例えば、画像の幅をセットするscaleというマクロを定義してみましょう。
remark.macros.scale = function(w) {
var url = this;
return '<img src="' + url + '" style="width: ' + w + '" />';
};
このマクロを使うと、次のようなMarkdownが
次のようなHTMLに変換されます。
<img src="image.jpg" style="width: 50%" />
すなわち、よりクリーンな疑似MarkdownからHTMLを生成できる、ということです。
マクロをスライドに組み込むには、まずマクロを適当なjsファイル（例えばmacros.js）に保存しておき、nature以下のbeforeInitオプションで読み込み指定します。
output:
xaringan::moon_reader:
nature:
beforeInit: "macros.js"
このオプションは任意のJavaScriptコードを、remark.jsがスライドを初期化する前に読み込むのに利用できます。
7 xaringanの欠点
最後にこのパッケージの欠点について触れておきましょう。
xaringanはもともとニンジャのために作られたパッケージです。すなわち、CSSを知っていれば自由にスタイルをカスタマイズできますが、さもなくばデフォルトのテーマを受け入れるしかありません。CSSと戯れることは楽しく実りの多いものですが、時間を簡単に浪費してしまう危険性をはらんでいます。あなたの美的感覚は時間と共に変化するかもしれません。あなたはスタイルの微調整をし続けることになるでしょう。
先に述べたように、xaringanのスライドはデフォルトではself-containedではありません。スライドがself-containedでなければならず、サーバーに配置することも望めない場合は、xaringanはあまり良い選択肢と言えないでしょう。
HTMLウィジェットはxaringanで上手く動作しないことがあります。これは将来的には改善されると思いますが、技術的にはやや難しい問題です。
Google Chromeを使ってスライドのPDFを生成したいと考える場合は、はじめにスライドを一通り表示しておくことをおすすめします。これにより、スライドの内容が確実にレンダリングされます。この作業を行わない場合、MathJaxやHTMLウィジェットなどが正しく表示されない可能性があります。