html_document(self_contained = FALSE) で出力した時の携帯性をあげるextra_dependencies引数

by
カテゴリ:
タグ:

rmarkdown::html_document関数には、self_contained引数がFALSEな時でも依存しているJavaScriptやCSSをポータブルにするために、extra_dependencies引数が用意されています。本記事ではこの引数の使い方について紹介します。

使い方と何が起きるか

htmltools::htmlDependency関数が返すhtml_dependencyクラスオブジェクトを束ねたlistを指定します。 htmltools::htmlDependencyの使い方については、ドキュメントを参照してください。

htmltools::htmlDependency関数に指定したJavaScriptファイルやCSSファイル、meta情報は出力されるHTMLファイルの<head>〜</head>の間に記述されます。 self_contained = FALSE時は、依存対象をRmdファイルと同じディレクトリ下に配置した子ディレクトリの中にコピーし、出力されたHTMLファイルから相対パスで参照できるようにします。

子ディレクトリ名の既定値はRmdファイルの名前に_filesとサフィックスしたものです。変更するにはrmarkdown::html_document関数のlib_dir引数を指定してください。

どういう時に使うのか

主にrmarkdown::html_documentを拡張するフォーマットをパッケージ化する時、 JavaScriptライブラリやCSSフレームワークをパッケージに同梱し、オフラインでも利用できるようにするために用います。

どういう時に使わないのか

  • self_contained = TRUEな運用しかしない時。
  • self_contained = FALSEな運用をするが、
    • 依存対象がRmdファイルから相対パスで参照しやすい範囲に依存対象が配置されている時。
    • includes引数を設定すれば十分な時。
      • HTMLファイルにJavaScriptやCSSをべた書きしていて、強制的にself_containedされても問題ない
      • 依存対象はネットワーク接続時にCDN経由で利用できれば十分
        • たとえばMathJaxやKaTeXなどの数式レンダリングエンジン (参考: 先日の記事)

メモ

以下は個人的なメモ書き。

経緯

minidownパッケージを作り過程で、パッケージに同梱したCSSフレームワークをポータブルに利用できるようにしたかった。そこで、rmarkdown::html_document(self_contained = FALSE)出力時に、出力先と同じディレクトリツリー下にBootstrap関連のファイルをコピーする方法が知りたかった。

調べ方

経緯についてrmarkdown::html_documentのソースを見ると、extra_dependenciesを利用しているとすぐわかりました。

そこで引数の使い方を調べるべく、 ?rmarkdown::html_documentを参照したところ、 rmarkdown::html_document_baseに引き渡すとあります。遡って参照するとExtra dependenciesとの説明があります。これでは引数名以上の情報が一切得られません1。

しかたがないので、rmarkdown::html_documentのソースコードを見てみましょう。すると、extra_dependencies引数は以下のような追加処理をうけた上で、 rmarkdown::html_document_baseのextra_dependencies引数に渡されます。

extra_dependencies <- append(extra_dependencies,
                             list(html_dependency_jquery(),
                                  html_dependency_jqueryui(),
                                  html_dependency_tocify()))

extra_dependenciesにappendしているlistは以下の通り、 html_dependencyクラスオブジェクトの集まりです。

library(rmarkdown)
appended_dependencies <-
  list(html_dependency_jquery(),
       html_dependency_jqueryui(),
       html_dependency_tocify())
str(lapply(appended_dependencies, class))
#> List of 3
#>  $ : chr "html_dependency"
#>  $ : chr "html_dependency"
#>  $ : chr "html_dependency"

html_dependencyクラスオブジェクトの作り方を見るため rmarkdown::html_dependency_jqueryのソースコードを覗いてみましょう。すると、htmltools::htmlDependencyを使えばいいとがわかります。

rmarkdown::html_dependency_jquery
#> function()  {
#> 
#>   htmlDependency(
#>     name = "jquery",
#>     version = "1.11.3",
#>     src = pkg_file("rmd/h/jquery"),
#>     script = "jquery.min.js")
#> }
#> <bytecode: 0x5615ce6001c8>
#> <environment: namespace:rmarkdown>

  1. 改善案をPR #1818しておいた。↩︎