1 Prerequisites

Bioconductor R Markdown format is build on top of R package bookdown, 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.12.3). See the pandoc installation instructions for details on installing pandoc for your platform.

2 Getting started

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_document2 or BiocStyle::pdf_document2 as output format and add vignette metadata in the document header:

    ---
    title: "Vignette Title"
    author: "Vignette Author"
    package: PackageName
    output: 
      BiocStyle::html_document2
    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_document2 and pdf_document2 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.

2.1 Use with R markdown v1

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'))
```

3 Document header

3.1 Author affiliations

The author field allows for specifing author names along with affiliation and email information.

In the basic case, when no additional information apart from author names is provided, these can be entered as a single character string

author: "Single Author"

or a list

author:
- First Author
- Second Author
- Last Author

which will print as “First Author, Second Author and Last Author”.

Author affiliations and emails can be entered in named sublists of the author list. Multiple affiliations per author can be specified this way.

author:
- name: First Author
  affiliation: 
  - Shared affiliation
  - Additional affiliation
- name: Second Author
  affiliation: Shared affiliation
  email: corresponding@author.com

A list of unique affiliations will be displayed below the authors, similar as in this document.

For clarity, compactness, and to avoid errors, repeated nodes in YAML header can be initially denoted by an anchor entered with an ampersand &, and later referenced with an asterisk *. For example, the above affiliation metadata is equivalent to the shorthand notation

author:
- name: First Author
  affiliation: 
  - &id Shared affiliation
  - Additional affiliation
- name: Second Author
  affiliation: *id
  email: corresponding@author.com

3.2 Abstract and running headers

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_document2
---

The shorttitle option specifies the title used in running headers instead of the document title.2 only relevant to PDF output

4 Style macros

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 no