Output Metadata¶

• R Markdown Insert Image
• R Markdown Tutorial
• R Markdown List

We normally think of R Markdown documents as producing a single outputartifact, such as an HTML or PDF file. The rmarkdown package allows reportauthors to emit additional output metadata from their report. RStudio Connecttakes advantage of this metadata, allowing output files, custom emailsubjects, and additional email attachments.

R Markdown¶ Output Metadata¶. We normally think of R Markdown documents as producing a single output artifact, such as an HTML or PDF file. The rmarkdown package allows report authors to emit additional output metadata from their report. RStudio Connect takes advantage of this metadata, allowing output files, custom email subjects, and additional email attachments. The first official book authored by the core R Markdown developers that provides a comprehensive and accurate reference to the R Markdown ecosystem. With R Markdown, you can easily create reproducible data analysis reports, presentations, dashboards, interactive applications, books, dissertations, websites, and journal articles, while enjoying the simplicity of Markdown and the great power of. R markdownis a particular kind of markdown document. Authors should be cautious about following formatting advice for other types of markdown when working on R markdown. The distinguishing feature of R markdownis that it cooperates with R. Like LATEX with Sweave, code chunks can be included. When the document is compiled, the code is executed. R markdown knitr rstudio r-markdown. Follow edited Oct 26 '12 at 16:36. 53k 11 11 gold badges 151 151 silver badges 179 179 bronze badges.

There are two ways to set output metadata: in the YAML header and in R codechunks.

The YAML header is a good place to configure default values for metadata thatyou always want to emit. All output metadata lives under thermd_output_metadata section in the YAML:

You can also use R code to set output metadata. This is useful if you wantmetadata to vary based on conditions or variables within your code.

Your R code can also read the current state of your output metadata. This canhelp you gradually alter this information as the report runs.

Note

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

Output Files¶

Introduction to Output Files¶

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

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

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'srmd_output_metadata section under rsc_output_files, like so:

rsc_output_files takes a list of names of files that should be availableafter the report has rendered. If you list a file that does not exist afterrendering your report, Connect will log a message but continue trying toprocessing the other files listed. If the output files are not generatedduring the rendering of your report, then you need to list them as resourcefiles when you upload your report to Connect. See ResourceFiles for more information.

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

Output files can be contained within sub-directories; the relative directorystructure is maintained.

To include a directory:

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

Because output files are versioned along with the rendering of their report,they also benefit from historical views. In the example above, if you viewa 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.

Accessing output files over HTTP¶

Content deployed to http://connect.mycompany.com/content/42/ will have itsoutput files available under that URL path. An output file nameddaily-summary.csv will be available at the URLhttp://connect.mycompany.com/content/42/daily-summary.csv.

The URL for your content is the same as its 'Open Solo' location and isavailable in the RStudio Connect dashboard.

Resource Files¶

If you want RStudio Connect to host a file that you have in your report's sourcedirectory on your computer, and that file is not generated by the report whenyou render it, then you will need to mark that file as a resource file. Like anoutput file, a resource file can be a plot, a data file, or any other artifactthat exists as a file. You can use the RStudio IDE to select resource files, oryou can list them in the R Markdown header:

Unlike rsc_output_files, the resource_files key is not nested underrmd_output_metadata. If you do not list your resource files underresource_files, then you will need to add them manually using the 'AddMore...' button when deploying from the IDE. See the Publishingsection for more information on publishing additionalresource files.

Email Customization¶

RStudio Connect makes it easy to schedule reports that distribute emails. Theseemails, by default, contain a link to the report. However, it is possible tofully customize the email, and distribute results directly tousers without requiring them to leave their inbox.

There are two approaches for customizing email in Connect. One approach is todirectly set R Markdown OutputMetadata. This option is the mostflexible, but also the hardest to use. The second approach is to use theblastula package. Using the blastulapackage is the easiest way to get started and is recommended for most use cases.

Getting Started with Custom Emails¶

To get started with custom emails, we recommend using theblastula package. The easiest way tostart is by installing the package and using the included example:

This command will create a new folder in your workspace with a number of examplefiles. In general, the approach when using blastula is to create a new RMarkdown document responsible for crafting the email. This R Markdown documentis then attached to your original document by including the following code inthe main R Markdown file:

Info

This code is an example from the final code chunk found inconnect-example-main.Rmd Rendering the main report will create a previewof the custom email. When you publish to RStudio Connect, simply include thechild R Markdown document responsible for the email as a supporting file.

Using R Markdown Metadata¶

Instead of using the blastula package, it is possible to construct custom emails using R Markdown Output Metadata. A quick summary of the output metadata options are:

To set an option, use code like:

The following sections describe the individual options in more detail.

Email Subject¶

You can customize the subject line used when an email of a report isgenerated. RStudio Connect uses the output metadata entry namedrsc_email_subject as email subject. A report without an rsc_email_subjectentry uses its published document name.

Use the YAML header to specify a simple, static text override of the emailsubject:

Set the email subject in an R code chunk if you need to dynamically build thesubject:

The RSC_EMAIL_SUBJECT environment variable contains the name of yourpublished report, which also acts as the default email subject. Thisenvironment variable is helpful if you want to add, but not fully replace thesubject.

Note

The value of RSC_EMAIL_SUBJECT is computed when your report is rendered.Changes to the report name will be incorporated into subsequent renderings.

You can also read the current subject from the output metadata toincrementally compose a final subject.

Email Body¶

A report can customize the message body used when an email for that report issent. RStudio Connect uses the output metadata entry namedrsc_email_body_text for plain-text bodies and rsc_email_body_html for HTMLbodies. A report with neither entry uses an automatically generated,plain-text body with a link to the report's URL.

Text Message Bodies¶

Use the YAML header to specify a simple, static text override of the emailbody:

The message in the email client would look similar to the following:

Set the body text in an R code chunk if you need to dynamically build themessage:

You can also read the current body from the output metadata toincrementally compose a final body.

The glue package can help with more complicatedformatting.

HTML Message Bodies¶

The rsc_email_body_html attribute specifies an HTML-formatted message body.RStudio Connect sets the content-type of the message so that most emailclients will display the HTML message correctly.

Note

Use rsc_email_body_text together with rsc_email_body_html to supply textthat older email clients can display while allowing newer clients to displayyour rich content.

The YAML header can specify a simple, static HTML override of the email body:

You can build the HTML message dynamically:

Composing and styling HTML email messages is different than buildingtraditional web pages. Email messages cannot embed scripts nor referenceexternal stylesheets. Email clients may implement additional restrictions.

Note

Not all email clients display HTML messages exactly the same. Send yourselfa test message to check basic formatting, then confirm with your audiencethat the message appears correctly in their email client.

Embedding Images in HTML Email¶

Info

For emails including images or tables, we highly recommend using the blastula package.

It is possible to embed images, such as plots, within HTML email, using thersc_email_images attribute in rmd_output_metadata. The embedded image musthave a Content ID that is used in the body of the HTML and when providing theimage to rsc_email_images, and the image itself must be base64-encoded. Hereis an example:

Including URLs and Other Details¶

You may want to customize your email with a link to the location of the reportin RStudio Connect or to give your email recipients a way to manage their emailsubscription. RStudio Connect provides the R Markdown render with environmentvariables that can be referenced from your code.

Note

The value of RSC_REPORT_NAME is computed when your report is rendered.Changes to the report name will be incorporated into subsequent renderings.

The final values of the URL environment variables are not known prior to rendering. RStudio Connect renders your document using placeholder values for these environment variables. The placeholder values are replaced when constructing the final email message. These URLs are not appropriate for use in the body of your report.

Use the Sys.getenv() function to get the values for these environmentvariables in your report. When rendering your report outside of RStudio Connect,these environment variables will not have values. Use the second argument toSys.getenv() to provide a temporary value.

You can use these variables anywhere within your email body or footer.

Email Attachments¶

An attachment is an output file that will be attached to an emailed report. Youcan specify email attachments as an argument to theblastulaattach_connect_emailfunction, or using the rsc_email_attachments R Markdown Output Metadata.

For example, using blastula:

For example, using output metadata:

For nested files, include the relative path:

An email attachment will be accessible via HTTP just like an output file, andyou 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 yourorganization. Connect is not aware of those limitations. Please work withyour systems administrators / IT organization if you have trouble deliveringfile attachments.

Conditionally Sending Email¶

By default, reports can be configured to run on a regular schedule. However, youmay only want to send an email to stakeholders under certain conditions. Forexample, you could have a report that runs every day to check supply levels, butonly sends an email notification if supplies dip below a critical threshold.

This behavior can be configured with the blastula package or using R MarkdownOutput Metadata.

Using blastula you can craft an if statement around the call to attach_connect_email:

Using R Markdown Output Metadata follows a similar pattern with an if statement:

Suppress Attaching Report To Email¶

By default, Connect adds the generated document as an attachment to emailmessages for that report. You can prevent this attachment from your R Markdownreport by giving the rsc_email_suppress_report_attachment metadata property alogical (Boolean) value or using the attach_output = FALSE argument inblastula::attach_connect_email.

Note

Attachments configured by the rsc_email_attachments metadata property(seecEmail Attachments) are still attachedand not affected by the rsc_email_suppress_report_attachment setting.

Tracking Visits¶

Connect records visits to R Markdown documents and lets you see:

• Which documents were viewed
• When the documents were viewed
• Who viewed the documents

Details about visits are also recorded for parameterized R Markdown documentsand other types of rendered and static content.

An overview of recent activity is available in the RStudio Connect dashboard.See the Content Settings Panel section to learn more.

Details about each visit are available through the InstrumentationAPIs. Use these records to perform your ownanalysis. Code examples showing how to obtain this data can be found in theUser Activity section of the RStudio Connect:Server API Cookbook.

2.5 Markdown syntax

R Markdown Insert Image

The text in an R Markdown document is written with the Markdown syntax. Precisely speaking, it is Pandoc’s Markdown. There are many flavors of Markdown invented by different people, and Pandoc’s flavor is the most comprehensive one to our knowledge. You can find the full documentation of Pandoc’s Markdown at https://pandoc.org/MANUAL.html. We strongly recommend that you read this page at least once to know all the possibilities with Pandoc’s Markdown, even if you will not use all of them. This section is adapted from Section 2.1 of Xie (2016), and only covers a small subset of Pandoc’s Markdown syntax.

2.5.1 Inline formatting

Inline text will be italic if surrounded by underscores or asterisks, e.g., _text_ or *text*. Bold text is produced using a pair of double asterisks (**text**). A pair of tildes (~) turn text to a subscript (e.g., H~3~PO~4~ renders H₃PO₄). A pair of carets (^) produce a superscript (e.g., Cu^2+^ renders Cu²⁺).

To mark text as inline code, use a pair of backticks, e.g., `code`. To include (n) literal backticks, use at least (n+1) backticks outside, e.g., you can use four backticks to preserve three backtick inside: ```` ```code``` ````, which is rendered as ```code```.

Hyperlinks are created using the syntax [text](link), e.g., [RStudio](https://www.rstudio.com). The syntax for images is similar: just add an exclamation mark, e.g., ![alt text or image title](path/to/image). Footnotes are put inside the square brackets after a caret ^[], e.g., ^[This is a footnote.].

There are multiple ways to insert citations, and we recommend that you use BibTeX databases, because they work better when the output format is LaTeX/PDF. Section 2.8 of Xie (2016) has explained the details. The key idea is that when you have a BibTeX database (a plain-text file with the conventional filename extension .bib) that contains entries like:

You may add a field named bibliography to the YAML metadata, and set its value to the path of the BibTeX file. Then in Markdown, you may use @R-base (which generates “R Core Team (2021)”) or [@R-base] (which generates “(R Core Team 2021)”) to reference the BibTeX entry. Pandoc will automatically generated a list of references in the end of the document.

2.5.2 Block-level elements

Section headers can be written after a number of pound signs, e.g.,

If you do not want a certain heading to be numbered, you can add {-} or {.unnumbered} after the heading, e.g.,

Unordered list items start with *, -, or +, and you can nest one list within another list by indenting the sub-list, e.g.,

The output is:

• one item
• one item
• one item
  • one more item
  • one more item
  • one more item

Ordered list items start with numbers (you can also nest lists within lists), e.g.,

The output does not look too much different with the Markdown source:

1. the first item
2. the second item
3. the third item
   • one unordered item
   • one unordered item

Blockquotes are written after >, e.g.,

The actual output (we customized the style for blockquotes in this book):

“I thoroughly disapprove of duels. If a man should challenge me,I would take him kindly and forgivingly by the hand and lead himto a quiet place and kill him.”

— Mark Twain

Plain code blocks can be written after three or more backticks, and you can also indent the blocks by four spaces, e.g.,

In general, you’d better leave at least one empty line between adjacent but different elements, e.g., a header and a paragraph. This is to avoid ambiguity to the Markdown renderer. For example, does “#” indicate a header below?

And does “-” mean a bullet point below?

Different flavors of Markdown may produce different results if there are no blank lines.

2.5.3 Math expressions

Inline LaTeX equations can be written in a pair of dollar signs using the LaTeX syntax, e.g., $f(k) = {n choose k} p^{k} (1-p)^{n-k}$ (actual output: (f(k)={n choose k}p^{k}(1-p)^{n-k})); math expressions of the display style can be written in a pair of double dollar signs, e.g., $$f(k) = {n choose k} p^{k} (1-p)^{n-k}$$, and the output looks like this:

[fleft(kright)=binom{n}{k}p^kleft(1-pright)^{n-k}]

You can also use math environments inside $ $ or $$ $$, e.g.,

R Markdown Tutorial

[begin{array}{ccc}x_{11} & x_{12} & x_{13}x_{21} & x_{22} & x_{23}end{array}]

R Markdown List

[X = begin{bmatrix}1 & x_{1}1 & x_{2}1 & x_{3}end{bmatrix}]

[Theta = begin{pmatrix}alpha & betagamma & deltaend{pmatrix}]

[begin{vmatrix}a & bc & dend{vmatrix}=ad-bc]