It seems as though a few more details about how to do figures in R Markdown would be helpful. The executive summary is: put fig_caption: true under pdf_document: in the YAML block at the start of your R markdown files. Control whether a figure floats or not by leaving blank lines on both sides of the R code chunk that creates the figure.

First it might be helpful to add some more details on the knitting process.

  1. R markdown (.Rmd) to markdown (.md): this conversion is carried out by the knitr package, which is turn controlled by the rmarkdown package. knitr is responsible for knitting, running the R code in your code chunks (the triple-backticked ones) and saving the results into an ordinary markdown document that combines the discursive text and your program code and results from the original .Rmd. All the chunk options and details about graphics, etc. are documented on the knitr website. However, some of the complexities of knitr’s options are handled for you by a “wrapper” package, rmarkdown. It is rmarkdown that first processes the “YAML metadata block” at the start of your .Rmd file, the thing that says

    title: My title
    author: Your name here

    Thus you can adjust some knitting parameters with options in this block, as documented on the rmarkdown website. When you click “Knit PDF” in RStudio, rmarkdown is invoked, which in turn runs knitr. You can actually replicate this behavior by using the rmarkdown::render(filename) function yourself. (render then calls knitr::knit().) As the documentation for rmarkdown PDF output tells you, you can adjust some of the final PDF output results in the YAML metadata. For example, you can turn on figure captions with

            fig_caption: true

    You have already been using one pdf_document option, the xelatex: true flag that ensures you can use Unicode characters properly.

  2. markdown (.md) to LaTeX (.tex): this conversion is carried out by pandoc. Unless you set the pdf_document option keep_tex: true, rmarkdown deletes this file when it is done processing. Nonetheless, TeX is the intermediate format that makes the final conversion possible.

  3. LaTeX (.tex) to PDF (.pdf): this conversion is carried out by either pdflatex (default) or xelatex (as we have been doing); these are programs that process LaTeX code slightly differently. A number of options relating to the final appearance of the document come into play at this stage.

Figures and captions

In the first conversion stage, for each plot, a separate file is generated by R and saved in a folder (named xyz_files/figure-latex); a link to the image is inserted into the ordinary markdown. If your R code chunk has blank lines on both sides, the corresponding image link will also have blank lines on both sides; if your R code chunk is the middle of a block of text, like this:

Ordinary discursive text...
`​``{r my-chunk-name}
More text...

then the resulting markdown will look something like

Ordinary discursive text...
More text...

At the second conversion stage, from markdown to LaTeX, image links with blank lines on either side are converted into LaTeX markup for floating figures. If the chunk generating the plot has a fig.cap="your caption" option, and the pdf_document: option fig_caption: true has been set, then the figure also bears a number and a caption.

By contrast, if blank lines are lacking on one side or both of the image link, then the LaTeX code for inserting an image directly into the flow of text, without floating and without a caption, is generated. This is often useful (but if you do this, make sure your plot is well-labeled), and check that the plot is actually appearing the way you want it to. This happens regardless of whether you had a fig.cap chunk option or whether you set fig_caption in the YAML metadata.

What if you want a figure that does not float but you don’t have any text to add on either side? You can use the following template:

```{r in-text-fig, fig.width=4}
ggplot(...) + ...

The backslash by itself at the end of the line means: “a new line here” and counts as text next to the figure for the purposes of markdown-to-LaTeX conversion.

Cacheing eccentricities

In case of pandoc errors related to missing image files, you might try removing the knitr cache. If your file is named xyz.Rmd the cache is a folder named xyz_cache. You can always delete this without causing any harm; it is immediately recreated.