この記事の目的

私が大好きなRMarkdownについて、Tipsを集中的に連載しようという思いつきの企画です。あと自分の中で進めている別企画のメモという位置づけでもあります。なので大した中身はありません。

R Markdownとは

Markdown記法をベースに、チャンクという形でRのコードを記述して評価・出力することができるものです。RStudioのクイックリファレンスでは以下のように説明してあります:

R Markdown is an easy-to-write plain text format for creating dynamic documents and reports.

RStudioの"Knit HTML"でPandocに送っている内容

R MarkdownからHTMLを作成するにはPandocを通すのですが、色々なオプションがつけられてます。長いこと使っていると段々とその中身が気になってくるはずです。

このPandocに送っているコマンドを調べるには、{rmarkdown}や{knitr}の本体をちゃんと精読して理解すべきなんですが、そんな余裕は全くありません。そこでログをチェックしました。

RStudioで"knit HTML"ボタンをクリックすると、コンソールペインに新たに"R Markdown"というタブが生成され、ここにknitした内容が流れます。この中から、おそらくPandocに送っているであろうコマンドの内容を取り出してみることにします。なおMac環境でRStudioのVersionは0.99.764、パッケージは2015/12/03現在で最新版を利用しています:

/Applications/RStudio.app/Contents/MacOS/pandoc/pandoc +RTS -K512m -RTS sugukesu.utf8.md --to html --from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash-implicit_figures --output sugukesu.html --smart --email-obfuscation none --self-contained --standalone --section-divs --template /Library/Frameworks/R.framework/Versions/3.2/Resources/library/rmarkdown/rmd/h/default.html --variable 'theme:bootstrap' --include-in-header /var/folders/h5/x6_gxyl531jc9jdjzdb4hjh40000gn/T//RtmpUGdb6q/rmarkdown-strbd43da1a64b.html --mathjax --variable 'mathjax-url:https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML' --no-highlight --variable highlightjs=/Library/Frameworks/R.framework/Versions/3.2/Resources/library/rmarkdown/rmd/h/highlight

めっちゃ長いですし読みづらいです。

解説

説明のため勝手に改行したものがこちらです:

/Applications/RStudio.app/Contents/MacOS/pandoc/pandoc
 +RTS -K512m -RTS
 sugukesu.utf8.md
 --to html
 --from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash-implicit_figures
 --output sugukesu.html
 --smart
 --email-obfuscation none
 --self-contained
 --standalone
 --section-divs
 --template /Library/Frameworks/R.framework/Versions/3.2/Resources/library/rmarkdown/rmd/h/default.html
 --variable 'theme:bootstrap'
 --include-in-header /var/folders/h5/x6_gxyl531jc9jdjzdb4hjh40000gn/T//RtmpUGdb6q/rmarkdown-strbd43da1a64b.html
 --mathjax
 --variable 'mathjax-url:https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
 --no-highlight
 --variable highlightjs=/Library/Frameworks/R.framework/Versions/3.2/Resources/library/rmarkdown/rmd/h/highlight

やっぱ長い…。とりあえずわかったところを解説します。なお今回これを解読するにあたり、Pandoc ユーザーズガイド日本語版を参考にさせていただきました。ありがとうございます。

1行目: アプリケーションパス

/Applications/RStudio.app/Contents/MacOS/pandoc/pandoc

ここでは使用するPandocへのパスを指定しています。この通りRStudioは自前で組み込んだPandocを利用するようにデフォルトでなっています。

2行目: スタックサイズの指定(確保?)

 +RTS -K512m -RTS

Pandocが変換する際に使用するスタックサイズを指定(確保)しています。結構とってますね。

3行目: inputファイル

 sugukesu.utf8.md

変換元ファイルです。なおこのファイルは元の*.Rmdファイルをknitして生成されたmdファイルです¹。

4行目: 出力するファイル形式の指定

 --to html

出力するファイルをhtml形式にすると指定しています。

5行目: 入力するファイル形式の指定

ここは説明のため、改行をさらに加えます:

 --from
 markdown
+autolink_bare_uris
+ascii_identifiers
+tex_math_single_backslash
-implicit_figures

--fromは入力するファイル形式を指定するオプションです。この直後にmarkdownを指定していますが、これはPandoc Markdownとなります。これ以降に+hogeと続いているのは、Pancoc Markdownの拡張機能の付与です。knitではこれらが自動的に付与されるようになっています。

autolink_bare_urisは、ユーザーガイドでは以下のように説明されています:

リンクを<...>で囲まない場合でも、全ての絶対参照URIをリンクに変換します。

ascii_identifiersは、ユーザーガイドでは以下のように説明されています:

auto_identifiersにより生成された識別子を純粋なASCII文字に変えます。アクセント記号の付いた英字はアクセント記号のない英字に置換され、非ラテン文字は削除されます。

このauto_identifiersというのは、「見出し要素に自動的に一意のidを付与する」という機能です。これにより、各見出しにid=*と個別のidが割り当てられるようになり、リンクで参照しやすくなったりします。これをascii文字のみにキレイにするという機能です²。こういう機能があるんですね。

tex_math_single_backslashは、ユーザーガイドでは以下のように説明されています:

\(と\)で囲まれた全てのものがTeXのインライン数式として解釈されます。[と]で囲まれたものはTeXのディスプレイ数式として解釈されます。注意：この拡張の欠点は、(と[のエスケープが不可能になることです。

これは数式への対応を付与していますね。

implicit_figuresは、ユーザーガイドでは以下のように説明されています:

1つの段落に1つの画像のみを置いた場合、その画像はキャプション付き画像として生成されます。(以下省略)

画像を単独でぽんと置いた時に、キャプション付きにする機能です。ですがこれの前に-がついていますからこの機能を外しています。なるほど。

以上が5行目の内容で、要するに与えられたinputファイルをどのように解釈していくかを記述しているものだったんですね³。

6行目出力ファイル名

 --output sugukesu.html

これは出力するときのファイル名を指定しています。

7行目: タイポグラフィの校正

 --smart

ユーザーズガイドでは以下のように説明してあります:

タイポグラフィ的に正しく出力します。具体的には、直線状の引用符を曲がった引用符に、---をemダッシュ「—」に、--をenダッシュ「–」に、 ...を3点リーダーに変換します。また、(省略)

便利機能をオンにしている、ということですね。

8行目: e-mailのリンクアドレスを難読化

 --email-obfuscation none

HTML文書においてmailto:リンクを難読化する方法を指定します。 noneの場合は、リンクは難読化されません。javascriptの場合はJavaScriptを用いて難読化します。 referencesの場合は、メールアドレスの文字を10進または16進の数値参照により難読化します。

多分、e-mailのリンクをそのまま晒すのはえらいことになるから難読化する、という機能だと思います。ここではnoneが指定されていますのでOFFにしていますね。

9行目: 自己完結型かどうかの指定

 --self-contained

これは、htmlファイル内に画像へのリンクがある場合などはbase64などで埋め込み、該当htmlファイル単独でも問題なく表示できるようにする機能です。htmlファイルのサイズは大きくなりますが、jsも画像もすべて組み込まれた単一ファイルになるので、公開や配布が楽になります。

10行目: スタンドアロンモード

 --standalone

ユーザーズガイドでは以下のように説明があります:

スタンドアローンモード。適切なヘッダおよびフッタのついた出力を生成します。(略)

つまり、htmlのヘッダなどがちゃんとついた形式で出力する、というものです。ドキュメントとして出力するならこの機能は必須ですが、ウィジェットなどちょっと違った形式の場合は注意する必要があるでしょう。

11行目: 節を`<div>`で囲む

 --section-divs

節を<div>タグや<section>タグで囲むというものです。基本このままで問題ありません。

12-13行目: 出力ファイルのテンプレートを指定

 --template /Library/Frameworks/R.framework/Versions/3.2/Resources/library/rmarkdown/rmd/h/default.html
 --variable 'theme:bootstrap'

htmlに出力する際のテンプレートを指定しています。RStudioでは{rmarkdown}パッケージのデフォルトテンプレートを使用しているようですね。そして--variableでテーマ指定してます。デフォルトでbootstrapを使用していますね。

14行目: ヘッダに含めるファイルを指定

 --include-in-header /var/folders/h5/x6_gxyl531jc9jdjzdb4hjh40000gn/T//RtmpUGdb6q/rmarkdown-strbd43da1a64b.html

生成するhtmlに組み込むヘッダを指定しています。気になる方は、このパスの先にあるファイルをチェックしてみてください。

15-16行目: 数式まわりの設定

 --mathjax
 --variable 'mathjax-url:https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'

mathjaxはwebコンテンツで数式をキレイに出してくれるライブラリです。これを設定しています。標準ではオンライン上の最新版を指定するようになってるようです。

17行目: シンタックスハイライトまわりの設定

 --no-highlight
 --variable highlightjs=/Library/Frameworks/R.framework/Versions/3.2/Resources/library/rmarkdown/rmd/h/highlight

コードシンタックスハイライトをどうするかを指定しています。ここでは{rmarkdown}内にあるものを利用しているようです。

以上です。長いですが、それぞれに意味があることがわかりましたね。

最後に

R Markdownを使っていくと、自分で色々設定したくなることが出てくるはずです。ですがその時にこのデフォルトの設定を把握しておくことが一番の近道になります。

少しでも参考になれば幸いです。

Enjoy!

一時的なファイルで、Rmdのyamlでkeep_md: trueを指定していなければmdファイルは完了したら削除されます。 ↩
詳細は省略しますが、Rで日本語見出しを含むhtmlスライドを作成する際にトラブルが発生することがあります。これについては後日解説します。 ↩
この内容はカスタマイズ可能です。多分別記事で書きます。 ↩