Instructions on enabling Bioconductor style in R Markdown vignettes.
BiocStyle 2.35.0
Bioconductor R Markdown format is build on top of R package bookdown (Xie, Allaire, and Grolemund 2018), which in turn relies on rmarkdown and pandoc to compile the final output document. Therefore, unless you are using RStudio, you will need a recent version of pandoc (>= 1.17.2). See the pandoc installation instructions for details on installing pandoc for your platform.
To enable the Bioconductor style in your R Markdown vignette you need to:
Edit the DESCRIPTION
file by adding
VignetteBuilder: knitr
Suggests: BiocStyle, knitr, rmarkdown
Specify BiocStyle::html_document
or BiocStyle::pdf_document
as output
format and add vignette metadata in the document header:
---
title: "Vignette Title"
author: "Vignette Author"
package: PackageName
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.1 \VignetteIndexEntry
should match the title
of your vignette The
package
field which should contain the package name is used to print the
package version in the output document header. It is not necessary to specify
date
as by default the document compilation date will be automatically
included. See the following section for details on specifying author
affiliations and abstract.
BiocStyle’s html_document
and pdf_document
format functions extend the
corresponding original rmarkdown formats, so they accept the same arguments as
html_document
and pdf_document
, respectively. For example, use toc_float: true
to obtain a floating TOC as in this vignette.
Apart from the default markdown engine implemented in the rmarkdown package, it is also possible to compile Bioconductor documents with 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:
Edit the DESCRIPTION
file to include
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 is 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'))
```
Abstract can be entered in the corresponding field of the document front matter, as in the example below.
---
title: "Full title for title page"
shorttitle: "Short title for headers"
author: "Vignette Author"
package: PackageName
abstract: >
Document summary
output:
BiocStyle::pdf_document
---
The shorttitle
option specifies the title used in running headers instead of
the document title.2 only relevant to PDF output
BiocStyle introduces the following macros useful when referring to R packages:
Biocpkg("IRanges")
for Bioconductor software, annotation and
experiment data packages, including a link to the release landing page or if the
package is only in devel, to the devel landing page, IRanges.
CRANpkg("data.table")
for R packages available on CRAN,
including a link to the FHCRC CRAN mirror landing page, data.table.
Githubpkg("rstudio/rmarkdown")
for R packages available on
GitHub, including a link to the package repository, rmarkdown.
Rpackage("MyPkg")
for R packages that are not available on
Bioconductor, CRAN or GitHub; MyPkg.
These are meant to be called inline, e.g., `r Biocpkg("IRanges")`
.
The line length of output code chunks is set to the optimal width of typically
80 characters, so it is not neccessary to adjust it manually through
options("width")
.
BiocStyle comes with three predefined figure sizes. Regular figures not otherwise specified appear indented with respect to the paragraph text, as in the example below.
plot(cars)