# `rmdformats` usage

#### Julien Barnier

#### 2019-02-19

This R package provides ready-to-use HTML output formats and templates for RMarkdown documents. The goal is to produce clean documents “out of the box”, with or without the RStudio IDE.

## Formats

The package provides several HTML output formats :

- `material`
- `readthedown`
- `html_clean`
- `html_docco`

## Options

You can add the following options to your YAML preamble :

- `fig_width` : figures width, in inches
- `fig_height` : figures height, in inches
- `fig_caption` : toggle figure caption rendering
- `highlight` : syntax highlighting
- `thumbnails` : if TRUE, display content images as thumbnails
- `lightbox` : if TRUE, add lightbox effect to content images
- `gallery` : if TRUE, add navigation between images when displayed in lightbox
- `use_bookdown` : if TRUE, will use `bookdown` instead of `rmarkdown` for HTML rendering, thus providing section numbering and cross references.

Example preamble :

    ---
    title: "My document"
    date: "`r Sys.Date()`"
    author: John Doe
    output:
      rmdformats::readthedown:
        self_contained: true
        thumbnails: true
        lightbox: true
        gallery: false
        highlight: tango
    ---

## Creating a new document

### Within RStudio

Choose `File` > `New File...` > `R Markdown...`, then select `From Template`. You should then be able to create a new document from one of the package templates.

### Without RStudio

The `create.doc()` function allows you to create a new directory with a clean ready-to-use RMarkdown file. `create.doc()` gets two main arguments :

- `dirname` is the name of the folder and RMarkdown file to be created
- `format` is the format name (`"material"`, `"readthedown"`, `"html_clean"` or `"html_docco"`)

By default, a `Makefile` file will be created in the new folder for direct rendering from the command line.

## Rendering

### With RStudio

Rendering from within RStudio should be quite simple : just click the `Knit` button.

### Rendering from R

You can render your document into HTML directly from within R with the `render()` function from the `rmarkdown` package :

    library(rmarkdown)
    render("mydocument.Rmd")

### Rendering with the Makefile

If you created your `.Rmd` file with the `create.doc()` function, you can then generate HTML or PDF files with :

    make html
    make pdf

You can also clean out any generated files and cache with :

    make clean

## Extra features and helpers

Some extra features are available depending on the format :

- the `material` template split the document in pages at each `<h1>` header, and provides an animated navigation between these pages
- `readthedown` is fully responsive, with collapsible navigation
- `html_clean` and `readthedown` provide an automatic and dynamic table of contents
- all formats provide automatic thumbnails for figures with lightbox display
- all formats support code folding and tabbed sections in the same way as RStudio’s default HTML template

The package also provides a `create.doc()` function as well as RStudio document templates to easily generate an empty and ready to use rmarkdown file with several configuration directives.

Finally, it also provides the `pilltabs()` helper function, which allows to display a crosstab dynamically. See one of the output samples for a live example.