17.5 Knit ボタンをカスタマイズする (*)

17.5 `Knit` ボタンをカスタマイズする (*)

RStudio の Knit ボタンをクリックすると, 新規の R セッション内で rmarkdown::render() が呼び出され, 同じディレクトリに入力ファイルと同じ基底名の出力ファイルが出力されます. 例えば出力フォーマット html_document で example.Rmd を knit すると, example.html というファイルが作られます.

文書がどうレンダリングされるかをカスタマイズしたいという状況もあるでしょう. 例えば今日の日付を文書に含めたり, コンパイルした文書を別のディレクトリに出力したいというときです. このようなことは適切な output_file 引数を付けて rmarkdown::render() を呼び出すことで実現できるのですが (17.3節参照) , レポートをコンパイルするのに rmarkdown::render() をいちいち呼び出すことに頼るのは不便かもしれません.

文書の YAML フロントマターで knit フィールドを与えれば Knit ボタンの挙動を制御できます. このフィールドは, 主要な引数 input（入力 Rmd 文書のパス）を伴って関数を取ってくれますが, 現時点では他の引数は無視されます. 関数のソースコードを直接 knit コードに書くことも, R パッケージなどどこか別の場所に関数を置いてそれを呼び出すことも可能です. カスタム knit 関数が日常的に必要ならば, 毎度のように R Markdown 文書に関数のソースコードを繰り返し書くのではなく, パッケージに関数を置くことをお薦めします.

YAML に直接ソースコードを置くなら, 関数全体をパーレン () で囲まなければなりません. ソースコードが複数行になるなら, 最初の行以外の全ての行にスペース2つ分のインデントをしなければなりません. 例えば出力ファイル名にレンダリングした日付を含めたい場合, 次のような YAML コードが使用可能です.

---
knit: (function(input, ...) {
    rmarkdown::render(
      input,
      output_file = paste0(
        xfun::sans_ext(input), '-', Sys.Date(), '.html'
      ),
      envir = globalenv()
    )
  })
---

例えば 2019/07/29 に example.Rmd を knit したなら, 出力ファイル名は example-2019-07-29.html となります.

上記のアプローチは単純で直截的ですが, 関数が R Markdown 文書で使われるのが1度限りでないと, YAML に直接関数を埋め込むのは管理が難しくなります. そこで例えばパッケージ内に knit_with_date() という関数を作成するとよいでしょう.

#' RStudio 用のカスタム knit 関数
#'
#' @export
knit_with_date <- function(input, ...) {
  rmarkdown::render(
    input,
    output_file = paste0(
        xfun::sans_ext(input), '-', Sys.Date(), '.',
        xfun::file_ext(input)
    ),
    envir = globalenv()
  )
}

上記のコードを myPackage という名前のパッケージに追加すれば, 次のような YAML 設定を使いカスタム knit 関数を参照することが可能になります.

---
knit: myPackage::knit_with_date
---

?rmarkdown::render のヘルプページを見て, Knit ボタンの背後にある knit 関数のカスタマイズについて, さらなるアイディアを見つけるのもよいでしょう.