---
title: "Bioconductor style for HTML documents"
author: "Andrzej Oleś, Wolfgang Huber, Martin Morgan"
date: "`r doc_date()`"
package: "`r pkg_ver('BiocStyle')`"
abstract: >
Instructions on enabling _Bioconductor_ style
in your _R_ markdown vignettes.
vignette: >
%\VignetteIndexEntry{Bioconductor style for HTML documents}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
output:
BiocStyle::html_document
---
# Prerequisites
In order to build .Rmd documents the `r CRANpkg("rmarkdown")` package is necessary, which relies on [pandoc](http://johnmacfarlane.net/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 `r CRANpkg("rmarkdown")` package then you can install it from CRAN using
```{r rmarkdown, eval=FALSE}
install.packages("rmarkdown")
```
In this case a recent version of [pandoc](http://johnmacfarlane.net/pandoc/) (>= 1.12.3) is also required. See the [pandoc installation instructions](https://github.com/rstudio/rmarkdown/blob/master/PANDOC.md) 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.
```{r code, echo = FALSE}
## The following redefinitions are only for printing the verbatim header below
doc_date = function() "`r doc_date()`"
pkg_ver = function(name) sprintf("`r pkg_ver('%s')`", name)
```
---
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 `r CRANpkg('rmarkdown')` package,
it is also possible to compile Bioconductor documents using the older markdown v1 engine
from the package `r CRANpkg('markdown')`. There are some
differences in setup and the resulting output between these two
engines.
To use the `r CRANpkg('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)
- Add the following code chunk at the beginning of your `.Rmd`
vignettes
```{r style, echo = FALSE, results = 'asis'}`r ''`
BiocStyle::markdown()
```
The way of attaching CSS files when using
`r CRANpkg('markdown')` differs from how this done with `r CRANpkg('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'}`r ''`
BiocStyle::markdown(css.files = c('custom.css'))
```
# Style macros
```{r macro, echo=FALSE}
macro <- function(name, pkg, description)
sprintf('`` `r %s("%s")` `` %s %s', name, pkg,
description, do.call(name, list(pkg)))
```
`r Biocpkg("BiocStyle")` introduces the following macros useful when
referring to _R_ packages:
* `r macro("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,")`.
* `r macro("CRANpkg", "data.table", "for _R_ packages available on
CRAN, including a link to the FHCRC CRAN mirror landing page,")`.
* `r macro("Githubpkg", "rstudio/rmarkdown", "for _R_ packages
available on GitHub, including a link to the package repository,")`.
* `r macro("Rpackage", "MyPkg", "for _R_ packages that are _not_
available on _Bioconductor_, CRAN or GitHub;")`.
# Additional formatting features
Compared to the default markdown appearance the formatting differences
include:
* Images and tables appear centered, e.g.
```{r figure, fig.width=4.0, fig.height=4.4}
v = seq(0, 60i, length = 1000)
plot(abs(v)*exp(v), type = "l", col = "Royalblue")
```
* Tables are displayed with striped rows:
```markdown
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
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}.$$
# Session info
Here is the output of `sessionInfo()` on the system on which this
document was compiled:
```{r sessionInfo, echo=FALSE}
sessionInfo()
```
[R]: http://r-project.org
[RStudio]: http://www.rstudio.com/