Setup

Show whitespaces

It would be clever to check the option “Options->Code->Display->Show whitespace characters” in RStudio. Otherwise you will never know how many whitespaces you put at the end of a line, and then you may spend a lot of time figuring errors in paragraphs formatting. The rule of two spaces to end a paragraph is not the best feature of the markup language.

UTF8

If you use languages other than English to write your posts, do not forget to check “Options->Code->Saving->Default” to set text encoding to UTF8, otherwise knitr will produce gibberish.

Markdown tricks

Spaces in headers

Never forget to place a space after header markup code “##”. Otherwise knitr will parse a header’s text as an ordinary paragraph. Much to your surprise.

Numbering of paragraphs

Sometimes you will want to manually number paragraphs or sections of a text. Build in functionality allows for use of numbered lists but they are inconvenient in many cases. More so if you follow a paragraph number with a dot like 1. Some text it will be formatted as an element of a list. Precede this dot with backslash to trick the parser:
1\. Paragraph text .

Custom counters

You may create your own counter for paragraphs like

{r, echo=FALSE, include=FALSE} 
  pc1 <- 0
  nextpar() <- function(restart=FALSE)
  { 
    if(restart){ 
    pc1 <<-0 
  } 
  pc1 <<- pc1+1 return(pc1)
  }
}

and use it in inline R code at the beginning of paragraphs ‘r nextpar()’

Verbatim code

It is nightmare to quote code blocks with backticks. There is no convenient way to suppress estimation of inline R-code snippets. Backslashing of backticks does not work by whatever reason. The hacks to show verbatim code chunks may be found here.

The idea is to use a lot of backticks and put the new line marker after “r” in an inline `r ` code to confuse the parser. To quote this code envelope it with double backticks. The code above is produced by code:

`` `r
cnt<-cnt+1; cnt` ``

N+1 backticks code block is required to envelope N backticks code block (note also an awful construct with eval and “r ‘'"):

````
```{r, eval=TRUE}`r
''`
1 + 1
```
````

produces

```{r, eval=TRUE}`r
''` 
1 + 1
```

To summarize all this is very confusing and should be avoided.

Knitr

Extraction of R code

There is the useful function in knitr to extract all code chunks from an RMD file and store them in a new R file:

library(knitr)
purl("rmd_file.rmd", output = "r_code_file.R", documentation = 2)

Knitr mysteriously fails

Quite often knitr fails when as.numeric() function is called within a document with a non-convertible text as a data input. It complaints about failed call to stri_*utf8() function for UFT8 conversion. No such error arises when a code is run in interactive mode. The solution is to use function type.convert(x, …) instead. It allows to supplement a string that will be considered as NA (na.strings argument).

Bookdown and blogdown

Bibliography

The packages allow for separation a bibliography description from a main text. They support bibliography lists in BIB-format and formatting of references with (CSL-styles)[https://citationstyles.org/].

YAML-header then may be expanded with:

bibliography: bibliography_filename.bib 
link-citations: true
csl: bibliography_style_filename.csl

Then it is possible to place references in a text like @refenence1, [@refenence1], [- @refenence1], etc.

There are thousands of free CSL-styles in the GitHubrepository. There is the search interface for looking them up list.
For blog publications I prefer style “journal-of-web-semantics.csl”.

Extraction of pictures

If you are not aiming to publish to RPubs but still going to publish in HTML you may consider:
* To install and use bookdown and blogdown packages;
* To set the options in YAML header to extract pictures and an interim markdown file:

::html_page:blogdown:
    keep_md: yes
    self_contained: no

Update RStudio to v. 1.4

It contains Visual Editor for markup that will extremely increase you productivity. On the other hand it tends to remove whitespaces in your markup than may have confusing results.

1. R Markdown Cookbook by Yihui Xie, Christophe Dervieux, Emily Riederer

2. bookdown: Authoring Books and Technical Documents with R Markdown by Yihui Xie

3. RStusio markup lessons

4. Cheatsheet