Prerequisites
In order to build .Rmd documents the rmarkdown package is necessary, which relies on pandoc to compile the final output document. If you are working within a recent version of RStudio then both rmarkdown and pandoc should be already installed.
If you are missing the rmarkdown package then you can install it from CRAN using
install.packages("rmarkdown")
In this case a recent version of pandoc (>= 1.12.3) is also required. See the pandoc installation instructions for details on installing pandoc for your platform.
Authoring R markdown HTML package vignettes
To enable the Bioconductor style in your markdown (.Rmd) vignettes you need to:
Edit to the DESCRIPTION file by adding
VignetteBuilder: knitr
Suggests: BiocStyle, knitr, rmarkdown
Specify BiocStyle::html_document as the output format and add vignette metadata in the document header:
---
title: "Vignette Title"
author: "Vignette Author"
output:
BiocStyle::html_document
vignette: >
%\VignetteIndexEntry{Vignette Title}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
The vignette section is required in order to instruct R how to build the vignette. Note that the \VignetteIndexEntry should match the title of your vignette.
It is also possible to specify additional details such as:
- document compilation
date inserted using the helper function doc_date
package version specification added by pkg_ver- vignette
abstract
as in the following example. Note the inclusion of an additional style sheet custom.css by specifying it in the document header.
---
title: "Vignette Title"
author: "Vignette Author"
date: "`r doc_date()`"
package: "`r pkg_ver('BiocStyle')`"
abstract: >
Vignette Abstract
vignette: >
%\VignetteIndexEntry{Vignette Title}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
output:
BiocStyle::html_document:
css: custom.css
---
Use with R markdown v1
Apart from the default markdown engine implemented in the rmarkdown package, it is also possible to compile Bioconductor documents using the older markdown v1 engine from the package markdown. There are some differences in setup and the resulting output between these two engines.
To use the markdown vignette builder engine:
Add the following to the DESCRIPTION file
VignetteBuilder: knitr
Suggests: BiocStyle, knitr
Specify the vignette engine in the .Rmd files (inside HTML comments)
<!--
%% \VignetteEngine{knitr::knitr}
-->
Add the following code chunk at the beginning of your .Rmd vignettes
```{r style, echo = FALSE, results = 'asis'}
BiocStyle::markdown()
```
The way of attaching CSS files when using markdown differs from how this done with rmarkdown. In the former case additional style sheets can be used by providing them to the BiocStyle::markdown function. To include custom.css file use
```{r style, echo = FALSE, results = 'asis'}
BiocStyle::markdown(css.files = c('custom.css'))
```
Session info
Here is the output of sessionInfo() on the system on which this document was compiled:
## R version 3.3.1 (2016-06-21)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 14.04.4 LTS
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_US.UTF-8 LC_COLLATE=C
## [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] BiocStyle_2.0.3
##
## loaded via a namespace (and not attached):
## [1] magrittr_1.5 formatR_1.4 htmltools_0.3.5 tools_3.3.1
## [5] yaml_2.1.13 Rcpp_0.12.6 stringi_1.1.1 rmarkdown_1.0
## [9] knitr_1.13 stringr_1.0.0 digest_0.6.10 evaluate_0.9
