_html_document_format.Rmd

---
title: "HTML Documents"
output:
  html_document:
    toc: true
    toc_depth: 3
    df_print: paged
---

```{r setup, include=FALSE}
paste_and = function(x) {
  n = length(x)
  x = sprintf('`"%s"`', x)
  if (n <= 1) return(x)
  if (n == 2) return(paste(x[1], 'and', x[2]))
  paste0(paste(x[-n], collapse = ', '), ', and ', x[n])
}
```

## Overview

To create an HTML document from R Markdown you specify the `html_document` output format in the front-matter of your document:

    ---
    title: "Habits"
    author: John Doe
    date: March 22, 2005
    output: html_document
    ---

## Table of Contents

You can add a table of contents using the `toc` option and specify the depth of headers that it applies to using the `toc_depth` option. For example:

    ---
    title: "Habits"
    output:
      html_document:
        toc: true
        toc_depth: 2
    ---

If the table of contents depth isn't explicitly specified then it defaults to 3 (meaning that all level 1, 2, and 3 headers will be included in the table of contents).

### Floating TOC

You can specify the `toc_float` option to float the table of contents to the left of the main document content. The floating table of contents will always be visible even when the document is scrolled. For example:

    ---
    title: "Habits"
    output:
      html_document:
        toc: true
        toc_float: true
    ---

You may optionally specify a list of options for the `toc_float` parameter which control its behavior. Options include:

* `collapsed` (defaults to `TRUE`) controls whether the table of contents appers with only the top-level (e.g. H2) headers. When collapsed the table of contents is automatically expanded inline when necessary.

* `smooth_scroll` (defaults to `TRUE`) controls whether page scrolls are animated when table of contents items are navigated to via mouse clicks.

For example:

    ---
    title: "Habits"
    output:
      html_document:
        toc: true
        toc_float:
          collapsed: false
          smooth_scroll: false
    ---

#### Requirements

Support for floating table of contents is only available in very recent versions of the **rmarkdown** package. You can install the most current version as follows:

```r
install.packages("rmarkdown")
```

### Section Numbering

You can add section numbering to headers using the `number_sections` option:

    ---
    title: "Habits"
    output:
      html_document:
        toc: true
        number_sections: true
    ---

Note that if you do choose to use the `number_sections` option you will likely also want to use `#` (H1) headers in your document as `##` (H2) headers will include a decimal point.

## Tabbed Sections

You can organize content using tabs by applying the `.tabset` class attribute to headers within a document. This will cause all sub-headers of the header with the `.tabset` attribute to appear within tabs rather than as standalone sections. For example:

    ## Quarterly Results {.tabset}

    ### By Product

    (tab content)

    ### By Region

    (tab content)

You can also specify two additional attributes to control the appearance and behavior of the tabs. The `.tabset-fade` attribute causes the tabs to fade in and out when switching. The `.tabset-pills` attribute causes the visual appearance of the tabs to be "pill" rather than traditional tabs. For example:

    ## Quarterly Results {.tabset .tabset-fade .tabset-pills}

#### Requirements

Support for tabsets is only available in very recent versions of the **rmarkdown** package. You can install the most current version as follows:

```r
install.packages("rmarkdown")
```

## Appearance and Style

There are several options that control the appearance of HTML documents:

* `theme` specifies the Bootstrap theme to use for the page (themes are drawn from the [Bootswatch](http://bootswatch.com/3/) theme library). Valid themes include `r paste_and(rmarkdown:::themes())`. Pass null for no theme (in this case you can use the `css` parameter to add your own styles).

* `highlight` specifies the syntax highlighting style. Supported styles include `r paste_and(rmarkdown:::html_highlighters())`. Pass null to prevent syntax highlighting.

* `smart` indicates whether to produce typographically correct output, converting straight quotes to curly quotes, `---` to em-dashes, `--` to en-dashes, and `...` to ellipses. Note that `smart` is enabled by default.

For example:

    ---
    title: "Habits"
    output:
      html_document:
        theme: united
        highlight: tango
    ---

### Custom CSS

You can add your own CSS to an HTML document using the `css` option:

    ---
    title: "Habits"
    output:
      html_document:
        css: styles.css
    ---

If you want to provide all of the styles for the document from your own CSS you set the `theme` (and potentially `highlight`) to null:

    ---
    title: "Habits"
    output:
      html_document:
        theme: null
        highlight: null
        css: styles.css
    ---

You can also target specific sections of documents with custom CSS by adding ids or classes to section headers within your document. For example the following section
header:

    ## Next Steps {#nextsteps .emphasized}

Would enable you to apply CSS to all of its content using either of the following CSS selectors:

    #nextsteps {
       color: blue;
    }

    .emphasized {
       font-size: 1.2em;
    }


## Figure Options

There are a number of options that affect the output of figures within HTML documents:

* `fig_width` and  `fig_height` can be used to control the default figure width and height (7x5 is used by default)

* `fig_retina` Specifies the scaling to perform for retina displays (defaults to 2, which currently works for all widely used retina displays). Note that this only takes effect if you are using knitr >= 1.5.21. Set to `null` to prevent retina scaling.

* `fig_caption` controls whether figures are rendered with captions

* `dev` controls the graphics device used to render figures (defaults to png)

For example:

    ---
    title: "Habits"
    output:
      html_document:
        fig_width: 7
        fig_height: 6
        fig_caption: true
    ---

## Data Frame Printing

You can enhance the default display of data frames via the `df_print` option. Valid values include:

| Option  | Description  |
|------------|-------------------------------------------|
| default  | Call the [`print.data.frame`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/print.dataframe.html) generic method   |
| kable  | Use the [`knitr::kable`](https://www.rdocumentation.org/packages/knitr/versions/1.12.3/topics/kable) function. |
| tibble  | Use the [`tibble::print.tbl_df`](https://www.rdocumentation.org/packages/tibble/versions/1.2/topics/print.tbl_df) function.  |
| paged  |  Use the `rmarkdown::print.paged_df` function which creates a pageable HTML table. |

### Paged Printing

When the `df_print` option is set to `paged`, tables are printed as an html
table with support for pagination over rows and columns. For instance,

    ---
    title: "Motor Trend Car Road Tests"
    output:
      html_document:
        df_print: paged
    ---
    
<pre class="markdown"><code>&#96;&#96;&#96;{r}
mtcars
&#96;&#96;&#96;
</code></pre>
```{r echo=FALSE, rows.print=5}
mtcars
```

The following options are avaialble:

| Option          | Description                                           |
|-----------------|-------------------------------------------------------|
| max.print       | The number of rows to print.                          |
| rows.print      | The number of rows to display.                        |
| cols.print      | The number of columns to display.                     |
| cols.min.print  | The minimum number of columns to display.             |
| pages.print     | The number of pages to display under page navigation. |
| paged.print     | When set to `FALSE` turns off paged tables.           |
| rownames.print  | When set to `FALSE` turns off row names.              | 

These options are specified under each chunk as follows:

<pre class="markdown"><code>&#96;&#96;&#96;{r cols.print=3, rows.print=3}
mtcars
&#96;&#96;&#96;
</code></pre>
```{r echo=FALSE, cols.print=3, rows.print=3}
mtcars
```

## Code Folding

When the knitr chunk option `echo = TRUE` is specified (the default behavior) the R source code within chunks is included within the rendered document. In some cases it may be appropriate to exclude code entirely (`echo = FALSE`) but in other cases you might want the code available but not visible by default. 

The `code_folding: hide` option enables you to include R code but have it hidden by default. Users can then choose to show hidden R code chunks either indvidually or document wide. For example:

    ---
    title: "Habits"
    output:
      html_document:
        code_folding: hide
    ---

You can specify `code_folding: show` to still show all R code by default but then allow users to hide the code if they wish.


#### Requirements

Support for code folding is only available in very recent versions of the **rmarkdown** package. You can install the most current version as follows:

```r
install.packages("rmarkdown")
```

## MathJax Equations

By default [MathJax](http://www.mathjax.org/) scripts are included in HTML documents for rendering LaTeX and MathML equations. You can use the `mathjax` option to control how MathJax is included:

* Specify "default" to use an https URL from the official MathJax CDN.

* Specify "local" to use a local version of MathJax (which is copied into the output directory). Note that when using "local" you also need to set the `self_contained` option to false.

* Specify an alternate URL to load MathJax from another location.

* Specify null to exclude MathJax entirely.

For example, to use a local copy of MathJax:

    ---
    title: "Habits"
    output:
      html_document:
        mathjax: local
        self_contained: false
    ---

To use a self-hosted copy of MathJax:

    ---
    title: "Habits"
    output:
      html_document:
        mathjax: "http://example.com/mathjax/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
    ---

To exclude MathJax entirely:

    ---
    title: "Habits"
    output:
      html_document:
        mathjax: null
    ---

## Document Dependencies

By default R Markdown produces standalone HTML files with no external dependencies, using data: URIs to incorporate the contents of linked scripts, stylesheets, images, and videos. This means you can share or publish the file just like you share Office documents or PDFs. If you'd rather have keep depenencies in external files you can specify `self_contained: false`. For example:

    ---
    title: "Habits"
    output:
      html_document:
        self_contained: false
    ---

Note that even for self contained documents MathJax is still loaded externally (this is necessary because of its size). If you want to serve MathJax locally then you should specify `mathjax: local` and `self_contained: false`.

One common reason keep dependencies external is for serving R Markdown documents from a website (external dependencies can be cached separately by browsers leading to faster page load times). In the case of serving multiple R Markdown documents you may also want to consolidate dependent library files (e.g. Bootstrap, MathJax, etc.) into a single directory shared by multiple documents. You can use the `lib_dir` option to do this, for example:

    ---
    title: "Habits"
    output:
      html_document:
        self_contained: false
        lib_dir: libs
    ---

## Advanced Customization

### Keeping Markdown

When knitr processes an R Markdown input file it creates a markdown (md) file which is subsequently tranformed into HTML by pandoc. If you want to keep a copy of the markdown file after rendering you can do so using the `keep_md` option:

    ---
    title: "Habits"
    output:
      html_document:
        keep_md: true
    ---

### Includes

You can do more advanced customization of output by including additional HTML content or by replacing the core pandoc template entirely. To include content in the document header or before/after the document body you use the `includes` option as follows:

    ---
    title: "Habits"
    output:
      html_document:
        includes:
          in_header: header.html
          before_body: doc_prefix.html
          after_body: doc_suffix.html
    ---

### Custom Templates

You can also replace the underlying pandoc template using the `template` option:

    ---
    title: "Habits"
    output:
      html_document:
        template: quarterly_report.html
    ---

Consult the documentation on [pandoc templates](http://pandoc.org/README.html#templates) for additional details on templates. You can also study the [default HTML template `default.html5`](https://github.com/jgm/pandoc-templates/) as an example.

### Markdown Extensions

By default R Markdown is defined as all pandoc markdown extensions with the following tweaks for backward compatibility with the markdown package:

```
+autolink_bare_uris
+ascii_identifier
+tex_math_single_backslash
```

You can enable or disable markdown extensions using the `md_extensions` option (you preface an option with `-` to disable and `+` to enable it). For example:

    ---
    title: "Habits"
    output:
      html_document:
        md_extensions: -autolink_bare_uris+hard_line_breaks
    ---

The above would disable the `autolink_bare_uris` extension and enable the `hard_line_breaks` extension. 

For more on available markdown extensions see the [pandoc markdown specification](http://pandoc.org/README.html#pandocs-markdown).

### Pandoc Arguments

If there are pandoc features you want to use that lack equivilants in the YAML options described above you can still use them by passing custom `pandoc_args`. For example:

    ---
    title: "Habits"
    output:
      html_document:
        pandoc_args: [
          "--title-prefix", "Foo",
          "--id-prefix", "Bar"
        ]
    ---

Documentation on all available pandoc arguments can be found in the [pandoc user guide](http://johnmacfarlane.net/pandoc/README.html#options).

## Shared Options

If you want to specify a set of default options to be shared by multiple documents within a directory you can include a file named `_output.yaml` within the directory. Note that no YAML delimeters or enclosing output object are used in this file. For example:

**\_output.yaml**

```yaml
html_document:
  self_contained: false
  theme: united
  highlight: textmate
```

All documents located in the same directory as `_output.yaml` will inherit its options. Options defined explicitly within documents will override those specified in the shared options file.

## HTML Fragments

If want to create an HTML fragment rather than a full HTML document you can use the [`html_fragment`](html_fragment_format.html) format. For example:

    ---
    output: html_fragment
    ---

Note that there is no title or author because fragments don't contain the standard header content that HTML documents do. HTML fragments are typically used for including snippets of HTML within larger web sites (e.g. blogs).

For additional information see the article on [HTML Fragments](html_fragment_format.html). Note that another good option for generating content to be included in larger websites is the [`md_document`](https://bookdown.org/yihui/rmarkdown/markdown-document.html) format, which generates markdown. For more information on this format see the article on [Markdown Documents](https://bookdown.org/yihui/rmarkdown/markdown-document.html).


## Creating a Website

You can render collections of R Markdown documents as a website using the `rmarkdown::render_site` function. See the article on [R Markdown Websites](https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html) for additional details.