Bioconductor style for HTML documents

Authoring markdown / HTML package vignettes

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

Use with rmarkdown vignette engine

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

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 refering to R packages:

Additional formatting features

Compared to the default markdown appearance the formatting differences include:

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.

Adding custom style sheets

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 r Githubpkg("rstudio/rmarkdown") (e.g. using recent versions of RStudio) 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.1.1 Patched (2014-09-25 r66681)
## Platform: x86_64-unknown-linux-gnu (64-bit)
## 
## 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_1.4.1
## 
## loaded via a namespace (and not attached):
## [1] evaluate_0.5.5 formatR_1.0    knitr_1.7      stringr_0.6.2 
## [5] tools_3.1.1