5 R Markdown

5.1 Output Files

5.1.1 Introduction to Output Files

Output files are files that live alongside your rendered report. They could be plots, data files, or other artifacts generated from the R code in your report. Output files will available via HTTP, and they will be versioned in the same way as your report. Output files are also subject to the same access controls as your report.

Connect will not process any output files that exist outside the working directory of the report that is rendering. That means that you cannot use absolute paths (e.g., /root/file.csv), relative paths (e.g., ../file.csv) or subdirectories (e.g., folder/file.csv).

5.1.2 How to Work with Output Files

There are two ways to specify which files should be treated as output files. The first is to list the file names in the R Markdown YAML header’s rmd_output_metadata section under rsc_output_files, like so:

---
title: "Report Title"
rmd_output_metadata:
  rsc_output_files:
    - "data.csv"
---

rsc_output_files takes a list of names of files that should be available after the report has rendered. If you list a file that does not exist after rendering your report, Connect will log a message but continue trying to processing the other files listed.

It is also possible to specify the list of output files from R code. For example:

rmarkdown::output_metadata$set("rsc_output_files" = list("data1.csv", "data2.csv"))

You can also make a link to share an output file from your report using the standard Markdown links as supported in R Markdown. For example, if you want to share a file named data.csv, you make a link to it in your report like this:

Here is the data used in my report: [data.csv](data.csv)

Because output files are versioned along with the rendering of their report, they also benefit from historical views. In the example above, if you view a historical rendering of the report, when you click on the data.csv link, you will get a download of the file from the same point in time as the report.

5.2 Email Customization

5.2.1 Email Subject Line

You can customize the subject line used when an email of a report is generated. RStudio Connect checks the R Markdown output metadata for a value named rsc_email_subject, and if it finds a value, it uses that value as the email subject.

There are two ways to set rsc_email_subject. If you want only a simple, static-text override of the title, you can set the value in the R Markdown YAML header. For example:

---
title: "Report Title"
rmd_output_metadata:
    rsc_email_subject: "My Email Subject Goes Here"
---

You can also set the email subject programmatically by setting the rsc_email_subject value from embedded R code. For example:

rmarkdown::output_metadata$set("rsc_email_subject" = "My Email Subject Goes Here")

Note that rmd_output_metadata names starting with rsc_ are reserved for use with RStudio Connect.

5.2.2 Email Attachments

An attachment is an output file that will be attached to an emailed report. You can specify email attachment files in essentially the same way as output files, but instead of listing them under rsc_output_files, you list them under rsc_email_attachments. For example:

---
title: "Report Title"
rmd_output_metadata:
  rsc_output_files:
    - "data.csv"
  rsc_email_attachments:
    - "attachment_1.csv"
    - "attachment_2.csv"
---

In the example above, we are specifying the file data.csv to be an output file and the files attachment_1.csv and attachment_2.csv to be email attachments.

It is also possible to specify the list of email attachments from R code. For example:

rmarkdown::output_metadata$set("rsc_email_attachments" = list("attachment_1.csv", "attachment_2.csv"))

An email attachment will be accessible via HTTP just like an output file, and you can make a link to it in your report in the same way.

Some mail systems have limitations on attachments in email messages. Attachments from your report need to follow the restrictions enforced by your organization. Connect is not aware of those limitations. Please work with your systems administrators / IT organization if you have trouble delivering file attachments.