16.8 R パッケージの R Markdown テンプレート

16.7節の図16.4では, 編集可能なパッケージビネットの HTML テンプレートを rmarkdown パッケージから取得する手順を表しています. この R Markdown ファイルには R パッケージのビネットを作るに当たっての適切なメタデータが詰め込まれています.

同様に, どのような R パッケージであっても, R Markdown テンプレートを同梱して, (この図で示しているように) ユーザが RStudio IDE を通してアクセスしたり, あるいはどのプラットフォーム上でも rmarkdown::draft() 関数でアクセスできるようにするとよいでしょう.

16.8.1 テンプレートのユースケースTemplate use-cases

テンプレートはカスタマイズされた文書構造・スタイル・コンテンツを共有するのに便利な方法です. 多くのすばらしい例が世に出回っています.

多くのテンプレートは入力済みのメタデータによって文書構造とスタイルを追加しています. すでに rmarkdown パッケージの (HTML の) ビネットテンプレートを例としてお見せしました. 同様に, rmdformats パッケージ (Barnier 2021) では様々なカスタムスタイル関数を output オプションに渡すテンプレートがいくつも提供されています.

その他のテンプレートではパッケージで必要になる文書の構文を例示しているものがあります. 例えば pagedown パッケージ (Xie et al. 2021) はポスター・履歴書・その他のページレイアウト用に無数のテンプレートを同梱しています. 同様に xaringan パッケージ (Xie 2021f) の忍者風のプレゼンテーションテンプレートは様々なスライドフォーマットのオプションに対する構文を例示しています.

テンプレートによってはパッケージの機能と構文を例示していることもあります. 例えば flexdashboard パッケージ (Iannone, Allaire, and Borges 2020) と learnr (Schloerke, Allaire, and Borges 2020) パッケージには,　サンプルのダッシュボートとチュートリアルをそれぞれ作成するために, パッケージから関数を呼び出すコードチャンク付きのテンプレートを同梱しています.

同様に, テンプレートには定型的なコンテンツの雛形を含んでいるものもあります. 例えば rticles パッケージ (Allaire, Xie, Dervieux, et al. 2021) にはたくさんテンプレートがあって, R Markdown 出力を様々な学術誌で要求されるスタイルとガイドラインに沿って調整できます. コンテンツの雛形は, 四半期レポートを作成するチームのようなところで組織的に設定する際にも便利です.

16.8.2 テンプレートの準備

usethis パッケージ (Wickham, Bryan, and Barrett 2021) にはテンプレートの作成に役に立つ関数があります. usethis::use_rmarkdown_template("テンプレート名") を実行すると, 必要なディレクトリ構造とファイルが自動で作成されます. テンプレート名は自分で付けましょう.

代わりに自分のテンプレートを手動で準備したいなら, inst/rmarkdown/templates のサブディレクトリを作成してください. このディレクトリ内に, 少なくとも2つのファイルを保存する必要があります.

  1. template.yaml という名前のファイル. これは RStudio IDE に対して, 人間が判読できるテンプレートの名称などの基本的なメタデータを与えます. 例えば以下のように 最低でも, このファイルは name と description フィールドを持っているべきです.

    name: テンプレートの例
description: このテンプレートが何をするか

    テンプレートが選択された時に新しいディレクトリを作成してほしいなら, create_dir: true を含めることもできます. 例えば learnr パッケージのテンプレートは create_dir: true を設定しており, 一方で flexdashboard パッケージのテンプレート はデフォルトの create_dir: false を使用しています. これらのテンプレートを RStudio で開いてみると, 様々なユーザの意図に気付くはずです.

  2. skeleton/skeleton.Rmd 内に保存された R Markdown 文書ファイル. これは R Markdown 文書に挿入したいどのようなコンテンツでも含めることができます.

オプションとして, skeleton フォルダにはスタイルシートや画像といった, 作ったテンプレートで使われる追加のリソースを含めることができます. これらのファイルはテンプレートとともにユーザのコンピュータに読み込まれます.

R Markdown のカスタムテンプレートを作るためのさらに詳細な情報は, RStudio Extensions と R Markdown Definitive Guide (Xie, Allaire, and Grolemund 2018) の Document Templates の章 を参照してください.

参考文献

Allaire, JJ, Yihui Xie, Christophe Dervieux, R Foundation, Hadley Wickham, Journal of Statistical Software, Ramnath Vaidyanathan, et al. 2021. Rticles: Article Formats for r Markdown. https://github.com/rstudio/rticles.
Barnier, Julien. 2021. Rmdformats: HTML Output Formats and Templates for Rmarkdown Documents. https://github.com/juba/rmdformats.
Iannone, Richard, JJ Allaire, and Barbara Borges. 2020. Flexdashboard: R Markdown Format for Flexible Dashboards. http://rmarkdown.rstudio.com/flexdashboard.
Schloerke, Barret, JJ Allaire, and Barbara Borges. 2020. Learnr: Interactive Tutorials for r. https://CRAN.R-project.org/package=learnr.
Wickham, Hadley, Jennifer Bryan, and Malcolm Barrett. 2021. Usethis: Automate Package and Project Setup. https://CRAN.R-project.org/package=usethis.
———. 2021f. Xaringan: Presentation Ninja. https://github.com/yihui/xaringan.
Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.
Xie, Yihui, Romain Lesur, Brent Thorne, and Xianying Tan. 2021. Pagedown: Paginate the HTML Output of r Markdown with CSS for Print. https://github.com/rstudio/pagedown.