Bioconductor style for HTML documents

Package: BiocStyle
Author: Andrzej Oles, Wolfgang Huber, Martin Morgan
Compilation date: 2015-04-16

Authoring markdown / HTML package vignettes

To enable the Bioconductor style in your markdown (.Rmd) vignettes:

Add the following to the DESCRIPTION file

VignetteBuilder: knitr
Suggests: BiocStyle, knitr

Specify the vignette engine in the .Rmd files (inside HTML comments)
```

```

Add the following code chunk at the beginning of your .Rmd vignettes

```{r style, echo = FALSE, results = 'asis'}
BiocStyle::markdown()
```

Use with rmarkdown vignette engine

To enable the newer rmarkdown (R Markdown v2) vignette builder engine you need to:

Edit to the DESCRIPTION file by adding

VignetteBuilder: knitr
Suggests: BiocStyle, knitr, rmarkdown

Set the vignette engine in your .Rmd files to

<!--
%% \VignetteEngine{knitr::rmarkdown}
-->

Include, in addition to the code chunk calling BiocStyle::markdown() (see above), the metadata header defining the output format. Add at the very top of your document
```
---
output:
  BiocStyle::html_document
---
```

The BiocStyle::html_document output format extends the rmarkdown build-in html_document format and you can use any of its parameters, e.g. set the title and add the table of contents

---
title: "Document Title"
output:
  BiocStyle::html_document:
    toc: true
---

Style macros

BiocStyle introduces the following macros useful when referring to R packages:

`r Biocpkg("IRanges")` for Bioconductor software packages, including a link to the release version landing page, IRanges.
`r Biocannopkg("org.Hs.eg.db")` for Bioconductor annotation packages, including a link to the release version landing page, org.Hs.eg.db.
`r Biocexptpkg("parathyroidSE")` for Bioconductor experiment data packages, including a link to the release version landing page, parathyroidSE.
`r CRANpkg("data.table")` for R packages available on CRAN, including a link to the FHCRC CRAN mirror landing page, data.table.
`r Githubpkg("rstudio/rmarkdown")` for R packages available on GitHub, including a link to the package repository, rmarkdown.
`r Rpackage("MyPkg")` for R packages that are not available on Bioconductor, CRAN or GitHub; MyPkg.

Additional formatting features

Compared to the default markdown appearance the formatting differences include:

Images and tables appear centered, e.g.

v = seq(0, 60i, length = 1000)
plot(abs(v)*exp(v), type = "l", col = "Royalblue")

plot of chunk figure

Tables are displayed with striped rows:
```
Fruit   | Price
------- | -----
bananas | 1.2
apples  | 1.0
oranges | 2.5
```
produces

Fruit Price

bananas 1.2

apples 1.0

oranges 2.5
Paragraph text is justified
External links open in new browser tab/window

Fruit	Price
bananas	1.2
apples	1.0
oranges	2.5

Math symbols can be included in markdown documents. You can write math expressions the same way you would in Latex, except some differences in escaping them.

Inline: For inline formulas use $P(x) = \frac{1}{2}$ or $P(x) = \frac{1}{2}$, which both render as $P(x) = \frac{1}{2}$.
Standalone: Math can be displayed in a separate line by writing $$P(x) = \frac{1}{2}$$ or \[P(x) = \frac{1}{2}.\], which both result in \[P(x) = \frac{1}{2}.\]

Adding custom style sheets

The way of attaching CSS files depends on whether the markdown or rmarkdown engine is used to compile the document. In the former case additional style sheets can be used by providing them to the BiocStyle::markdown function. To include my.css file use

```{r style, echo = FALSE, results = 'asis'}
BiocStyle::markdown(css.files = c('my.css'))
```

For example, you might want to include some code chunks containing shell commands and distinguish them by different formatting. For this, let the code chunk class be .sh

```{.sh}
ls
```

my.css

.sh {
  border-style: none;
  border-left: 2px #1a81c2 solid;
  padding: 0em 0em 0em 1em;
  font-weight: bold;
}

which results in

ls

If you are rendering your documents using rmarkdown (e.g. using recent versions ofRStudio) additional CSS style sheets need to be defined in header and not in the call to BiocStyle::markdown:

---
output:
  BiocStyle::html_document:
    css: my.css
---

Use with RStudio

Currently, there are two markdown engines build into RStudio: the older one based on the markdown package, and the newer one using the rmarkdown package. There are some differences in setup and the resulting output between these two engines.

Starting from RStudio version 0.98.932 markdown documents are by default compiled using the newer rmarkdown engine. You can override this and force RStudio to render your markdown documents using the former engine by adding a special comment to your source file:

<!-- rmarkdown v1 -->

Session info

Here is the output of sessionInfo() on the system on which this document was compiled:

## R version 3.2.0 RC (2015-04-08 r68161)
## Platform: x86_64-apple-darwin10.8.0 (64-bit)
## Running under: OS X 10.6.8 (Snow Leopard)
## 
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] BiocStyle_1.6.0
## 
## loaded via a namespace (and not attached):
## [1] formatR_1.1   tools_3.2.0   knitr_1.9     stringr_0.6.2 evaluate_0.6