# 1 Introduction

This is about preparing Rmarkdown documents that exploit the special features available in Web pages. It is a work in progress.

# 2 First, Study the Rmarkdown Basics

The stationery package includes a vignette that introduces the markdown philosophy and the Rmarkdown version of it. It shows how to use R (R Core Team 2018) code chunks. This document is focused on the special features that might be obtained with HTML documents.

# 3 How to Compile the Document

The stationery package includes a vignette stationery that explains the process of compiling the document. The document can be compiled either by starting R and using the stationery function named rmd2html or it can be compiled by the command line using the shell script rmd2html.sh that we provide with the package.

The rendered output is an HTML file that can be opened using any browser. The HTML document has figures and cascading style sheets embedded in it, so it is nearly self-contained (relies on MathJax web server and possibly some external javascript).

# 4 Special Features for Rmd into HTML documents.

Rmarkdown intended for an HTML backend can include HTML code. If Rmarkdown is missing syntax to achieve some purpose, then the HTML approach will generally get the job done.

Because many Rmarkdown authors are unfamiliar with HTML code, quite a few syntactic-shortcuts have been developed. As we explained in the Rmarkdown vignette, it is preferable to use the Rmarkdown syntax when it is available because this improves the portability of the document. However, when no markdown syntax exists, one must improvise.

In this section, we first emphasize 2 special features that are provided in our cascading style sheet that facilitate use of some pleasant HTML markup strategies. These are 1) colored callouts and 2) tabbed subsections.

## 4.1 Colored callouts

The stylesheet includes style code for “callout” sections. These were adapted from the HTML stylesheets in the bootstrap project.

A colored callout must begin as a level-4 markdown heading. The syntax begins with ####, and then after that some syntax that is, actually, HTML style code, is included. The colors for which we have provided are “gray”, “red”, “orange”, “blue”, and “green”.

### 4.1.1 Demonstrating callouts

#### 4.1.1.1 Gray Callout

The gray callout is created by this Rmarkdown code:


#### Gray Callout {.bs-callout .bs-callout-gray}


Perhaps “gray” is for wisdom. Perhaps it is just a visual separator between exciting colors like red and blue!

#### 4.1.1.2 Red Callout

Syntax:


#### Red Callout {.bs-callout .bs-callout-red}


Red callout is for danger, in the eyes of some authors. Other authors just think it is pretty.

#### 4.1.1.3 Orange Callout

Orange might be used for examples.


#### Orange Callout {.bs-callout .bs-callout-orange}


#### 4.1.1.4 Blue Callout


#### Blue Callout {.bs-callout .bs-callout-blue}


Blue is for correct answers, at least according to the color Nazis.

#### 4.1.1.5 Green Callout


#### Green Callout {.bs-callout .bs-callout-green}


Green is the color of the Earth, of course, so we use it for ideas, suggestions, or whatever we like.

#### 4.1.1.6 What is the meaning of the colors

At one time, we were calling naming these things by their purpose rather that colors. The purpose <==> color mapping was

purpose color
info blue
warning orange
danger red

However, we concluded that some people might like to use red for warnings or orange for danger. We are all about diversity and concluded it was superficial to use purpose-based names. Some of us use the colored callout regions simply for decoration, so we don’t name them by purpose anymore.

Some of our older Rmarkdown documents do use that approach, however.

#### 4.1.1.7 Other structures can be embedded in colored callout

This is an R code chunk embedded inside the red: colored callout:

dat <- data.frame(x=rnorm(1000), y=rpois(1000, l=7))
summary(dat)
       x                   y
Min.   :-3.128437   Min.   : 0.000
1st Qu.:-0.647860   1st Qu.: 5.000
Median : 0.054540   Median : 7.000
Mean   : 0.005542   Mean   : 6.809
3rd Qu.: 0.691346   3rd Qu.: 8.000
Max.   : 2.786802   Max.   :17.000  

words here!

## 4.6 Inserting images: Use HTML code

Pictures or graphics can be inserted into Rmarkdown documents. The usual markdown syntax for image inserts is

![alt text](image/location/file.png "Image Title Text")

That syntax is somewhat limiting, mostly because we cannot resize the images. Another limitation is that some graphics formats are not allowed. The suggested file formats are svg, png, and jpg, so graphics in pdf will not be usable as is.

To resize images, we need to resort to raw HTML code, which seems somewhat disappointing to many authors. HTML allows rescaling. We can specify both the width and the height of the image. In this example code, a png format file named “plot1.png” is inserted in the document.

<img src="ext_img/plot1.png" alt = "Floating .png"
width  = "308"
height = "216">


Authors who need to use graphics saved in other formats will need to convert to png, jpg, or svg. The Gold standard of format converters is the convert function of the ImageMagick suite of tools. It is also possible to open a PDF in some editors, such as the GNU Image Manipulation program (GIMP), and save as an image format. There are some websites that might be useful for this purpose, such as http://pdf2png.com.

## 4.7 International characters

If you can figure out how to insert characters with accents, they will display correctly. For example, Karl Gustav Jöreskog, Dag Sörbom, and Linda Muthén and Bengt Muthén. These are entered at the keyboard using editor-specific tools.

# 5 Illustration of Chunk Features

In the stationery package vignette named code_chunks, we explain the idea that in both and Rmarkdown, one can insert R code chunks that will be processed. There, we spell out a list of requirements for any chunk based system along with examples.

We run the same code chunks here, to compare the HTML output with PDF from the code_chunks vignette.

## 5.1 Chunks that do not generate graphics

1. A chunk that is evaluated, echoed, both input and output. This is a standard chunk, no chunk options are used:

The user will see both the input code and the output, each in a separate box:

set.seed(234234)
x <- rnorm(100)
mean(x)
[1] -0.1004232

Notice the code highlighting is not entirely successful, and is different from results we see in other backends.

2. A chunk with commands that are echoed into the document, but not evaluated (eval=F).

When the document is compiled, the reader will see the depiction of the code, which is (by default) beautified and reformatted:

set.seed(234234)
x <- rnorm(100)
mean(x)
3. A chunk that is evaluated, with output displayed, but code is not echoed (echo=F). It is not necessary to specify eval=T because that is a default.

The user will not see any code that runs, but only a result:

[1] 0.2024592
4. A hidden code chunk. A chunk that is evaluated, but neither is the input nor output displayed (include=F)

What is the grammatically correct way to say “did you see nothing?” You should not even see an empty box? After that, the object x exists in the on-going R session, it can be put to use.

## 5.2 Chunks with graphics

1. A chunk that creates a graph, and allows it to be inserted into the document, but the code is not echoed for the reader to see.

2. Save a graph in a file and display it at a later point.

This can be acheived by specifing: fig.show=“hold”, echo=F. Optionally we can specify the height and width of the figure with fig.height and fig.width (which are always in inches). The file will be saved in the current working directory.

hist(x, main = "Another Histogram")
3. A chunk that shows a series of plotting commands.

This is a named chunk that is not evaluated, but it is displayed to reader. The same code is then put to use twice in what follows.

par(mar = c(3,2,0.5,0.5))
cax <- 0.7 ## cex.axis
plot(c(0, 1), c(0, 1), xlim = c(0,1), ylim = c(0,1), type = "n", ann = FALSE, axes = FALSE)
rect(0, 0, 1, 1, col = "light grey", border = "grey")
axis(1, tck = 0.01, pos = 0, cex.axis = cax, padj = -2.8, lwd = 0.3,
at = seq(0, 1, by = 0.2), labels = c("", seq(0.2,0.8, by=0.2), ""))
axis(2, tck = 0.01, pos = 0, cex.axis = cax, padj = 2.8, lwd = 0.3,
at = seq(0, 1, by = 0.2), labels = c("", seq(0.2,0.8, by=0.2), ""))
mtext(expression(x), side = 1, line = 0.5, at = .5, cex = cax)
mtext(expression(y), side = 2, line = 0.5, at = .5, cex = cax)
mtext(c("Min x", "Max x"), side = 1, line = -0.5, at = c(0.05, 0.95), cex = cax)
mtext(c("Min y", "Max y"), side = 2, line = -0.5, at = c(0.05, 0.95), cex = cax)
lines(c(.6, .6, 0), c(0, .6, .6), lty = "dashed")
text(.6, .6, expression(paste("The location ",
group("(",list(x[i] == .6, y[i] == .6),")"))), pos = 3, cex = cax + 0.1)
points(.6, .6, pch = 16)

The first re-use of this code simply runs the whole chunk, and keeps the final figure. This figure is a png file that is embedded in the HTML document.

A special feature of knitr is the ability to keep the intermediate plots that are produced by each line. An inspection of the tmpout directory shows that this code created several graphs. Observe there are several files:

list.files("tmpout", pattern="p-chunk76.*png") 
 [1] "p-chunk76-1.png"  "p-chunk76-10.png" "p-chunk76-11.png"
[4] "p-chunk76-2.png"  "p-chunk76-3.png"  "p-chunk76-4.png"
[7] "p-chunk76-5.png"  "p-chunk76-6.png"  "p-chunk76-7.png"
[10] "p-chunk76-8.png"  "p-chunk76-9.png" 

In a way that is rather similar to the PDF backend, we use a backend-specific table structure to display four of the images. The display of the table’s caption is controlled by the style sheet.

<table border="0" cellpadding="0">
<caption>Figure: Table Array of Four Graphics</caption>
<tr><td><img src="tmpout/p-chunk76-4.png" height=350 width=350 alt = "a png"></td>
<td><img src="tmpout/p-chunk76-8.png" height=350 width=350 alt = "b png"></td></tr>
<tr><td><img src="tmpout/p-chunk76-9.png" height=350 width=350 alt = "c png"></td>
<td><img src="tmpout/p-chunk76-11.png" height=350 width=350 alt = "d png"> </td></tr>
</table>