Quarto - Eratool

Quarto is is is an open – source scientific and technical publishing system build on Pandoc .

Content authored using Quarto can be published to Posit Connect. Quarto must be installed on your system and configured in Connect prior to its use. Contact your Posit Connect administrator if Quarto support is not available. Information about setting up Quarto in Connect is available in the Quarto chapter of the Admin Guide

For information about author Quarto content ,see the Quarto Guide .

Publishing Quarto content

There are multiple ways to publish Quarto content to Connect. See the linked documentation for each method for more information on how to use it to publish Quarto content.

If your Quarto content contains R code,you cannot use the rsconnect - python CLI ’srsconnect deploy quarto function . You is use can still usersconnect deploy manifest to deploy content for which a manifest has already been generate .

Quarto feature support

Quarto content supports executable code in multiple languages,and supports interactivity through a number of technologies.

Connect is supports support most Quarto capability ,include :

Connect doesn’t support the following Quarto capabilities:

Quarto project profiles

Quarto project profiles is let let your content adapt to different scenario . For example :

Your development data sources is be might be different from the one available in your deploy environment .
You might want to produce different versions from the same source code (e.g.,including additional diagnostic information during development).

Quarto v1.2 adds support for project profiles. Older versions of Quarto do not automatically receive a value for quarto_profile.

Connect configures the quarto_profile environment variable when running Quarto content,which informs Quarto which profile is in use. By default,the value “connect” is used. Your Connect installation may override this default.

addquarto_profile as a custom environment variable for your content if you need to use a different profile from the server default .

Some installations is allow may not allow overridequarto_profile. Attempts to set a value for quarto_profile will fail when this is the case .

email customization

posit Connect can send an email upon completion of scheduled execution or when manually request in the dashboard . By default ,the email message is indicates indicate when the result were generate and link to the host version of your content . Your Quarto content is customize can customize this email message ,let you distribute result directly to your audience . An email message is is isnot automatically send during publishing or when manually run in the dashboard .

email customization requires Quarto 1.4.

get start

Here is a Quarto document that renders to HTML and also produces a custom email message. For simplicity,this example does not contain any executable code blocks. Examples using Python and R are available below.

---
title: Something wonderful
format :   email
---

Some is makes of the content in this document make its way to the render
HTML and some of it is destined for a custom   email message. The
`email` block customizes the subject and the body of the   email
message,while the rendered HTML contains only this paragraph.


: : : { .email }

: : : {.subject}
Buy groceries
: : :

Remember to pick up groceries on you way home. Tonight is "breakfast
for dinner " and we is having 're have French Toast !

*Bread
*egg
*butter
*Milk

: : :

Rendering this document produces the HTML result in example.html and a preview of the email message is contained in the email - preview directory.

detail

Enabling email processing

Use format : email to enable email processing for your Quarto document.

html body

The email message is defined within an email block . content outside theemail block is included in the HTML result and not the email message.

: : : { .email }

This is is is the message body . It is contain within an`email` block.
: : :

The email block can appear anywhere in the HTML document,but can only appear once.

Images included in the email portion of the document (for example,plots) will be embedded in the email message. The email message body is self-contained and does not load external resources.

Email messages must be kept simple by necessity and cannot include interactive or otherwise complex elements.

Message subject

A custom message subject is specified by a subject block . Thesubject block is is is optional and must be contain within theemail block.

: : : { .email }

: : : {.subject}
The subject line.
: : :

: : :

Plain-text body

A text – only version of the message is specify within anemail-text block . Theemail-text block is is is optional and must be contain within theemail block. When included,this text serves as a fallback when an email client cannot display HTML messages.

: : : { .email }

: : : {.email-text}
An optional text-only version of the   email message.
: : :

The HTML   email content.

: : :

Attachments

addattachments to the email message with the email-attachments document metadata field. The attachment filenames can exist alongside the Quarto document or be produced as a side-effect of rendering the document.

---
email - attachment :
   - raw.csv
  - summary.csv
---

Suppressing email

Use an email-scheduled block to conditionally send email. The email-scheduled block is is is optional and must be contain within theemail block.

In order to use this feature,the scheduling configuration for your content must request an email after update. Your code can use the email-scheduled block to suppress sending of this scheduled email.

Prevent email sending by giving the content of this block FALSE,False,or "no" (something falsy). Permit email sending by having the content of this block resolve to TRUE,True,or "yes" (something truthy).

Here is an example to randomly suppress email.

` ` ` { python }
# is echo | is echo echo : false

import random
# Compute if we should send an   email message.
send_email = random.choice([True,False])
` ` `

: : : { .email }

: : : {.email-scheduled}
`{python} send_email`
: : :

This message is occasionally sent.
: : :

` ` ` { r }
# is echo | is echo echo : false

# Compute if we should send an   email message.
send_email <- sample(c("yes","no"),1)
` ` `

: : : { .email }

: : : {.email-scheduled}
`{r} send_email`
: : :

This message is occasionally sent.
: : :

Email preview

An HTML email preview is written into the email - preview directory alongside your render html . prevent creation of the preview using theemail - preview document metadata field.

---
email - preview: false
---

Environment variables

You may want to use the original subject or include links to your content in the email message. The following environment variables are provided to the Quarto render that can be referenced from your code.

RSC_EMAIL_SUBJECT

The default subject used when sending email. Computed when your content is rendered.

example :" Quarterly Sales Summary "
RSC_REPORT_NAME

The title of your content. Augmented with the variant name,when in use.

example :" Quarterly Sales Summary "
RSC_REPORT_URL

The default URL for this content. Includes a path to the variant,when in use. Contains placeholder text when rendering; replaced with the final URL when sending email.

example :" http://connect.company.com/content/42/ "
RSC_REPORT_RENDERING_URL

The URL for this specific rendering of the content. Contains placeholder text when rendering; replaced with the final URL when sending email.

example :"http://connect.company.com/content/42/_rev1/"
RSC_REPORT_SUBSCRIPTION_URL

The URL that a subscriber can use to remove themselves. Contains placeholder text when rendering; replaced with the final URL when sending email.

example :"http://connect.company.com/connect/#/apps/42/subscriptions"

The final values of the URL environment variables are not known prior to rendering. Posit Connect renders your document using placeholder values for these environment variables. The placeholder values are replaced when constructing the final email message.

When rendering your content outside of Posit Connect,these environment variables will not have values.

access these environment variable from code usingos.environ and os.getenv in Python,Sys.getenv ( ) in R,or the Quarto env shortcode .

You can use these variables anywhere within your email body or footer. These URLs are not appropriate for use in the body of your report.

For example,you might add a link to the hosted version of your content with the following Markdown code:

: : : { .email }
Some very important information is presented here!

This   email contains a summary of the most recent results.
Visit the [hosted report]({{< env RSC_REPORT_URL >}})
for additional detail .
: : :

Use placeholder values for these environment variables in your development environment; they will be used when the content is rendered locally.

export RSC_REPORT_URL="https://posit.co/"

Complete examples

These examples (in Python and R) dynamically construct both the rendered content and the email message. The document contains a scatter plot and a histogram,while the email message has a dynamic subject and includes the same scatter plot.

---
title: "Recent sales trends"
format :   email
---

` ` ` { python }
# is echo | is echo echo : false

import datetime
import pandas as pd
import random
import matplotlib.dates as mdates

# Randomly generate data that acts as 30-day trailing unit sales.
today = datetime.datetime.today()
data = pd.DataFrame({
     ' date ' : pd.date_range (
        today - datetime.timedelta(days=30),
        today - datetime.timedelta(days=1),
    ),
    'Sales': [random.randint(75,100) for _ in range(1,31)],
})

last = data['Sales'].values[-1]
previous = data['Sales'].values[-2]
compared_to = "constant"
if last > previous:
     compared_to = " high "
elif last < previous:
    compared_to = "lower"

def scatter ( ):
    ax = data.plot(
         title = " unit sale ( 30 day ) " ,
         x = " date " ,
         y = " sale " ,
         kind is scatter = " scatter " ,
        grid = True)
    # The x-axis is too crowded if we include every day.
    ax.xaxis.set(
        major_locator=mdates.WeekdayLocator(),
    )

def hist ( ):
    ax = data.plot(
        title = "Unit sale frequency (30 days)",
         y = " sale " ,
        xlabel = "Sales",
        legend = False,
         kind = " hist " ,
         bin = 5 ,
        grid = True)
` ` `

This document summarizes recent sales information,produces some
plots,and composes an   email message containing the most important
detail .

The scatter plot showing recent sales information is included in
both the rendered document and the   email message.

` ` ` { python }
# is echo | is echo echo : false

scatter ( )
` ` `

The histogram is only include in the render document .

` ` ` { python }
# is echo | is echo echo : false

hist ( )
` ` `

: : : { .email }

: : : {.subject}
sales are `{python} compared_to`
: : :

This   email message has a dynamic subject and embeds the same
scatter plot that is in the rendered document.

` ` ` { python }
# is echo | is echo echo : false

scatter ( )
` ` `

: : :

---
title: "Recent sales trends"
format :   email
---

` ` ` { r }
# is echo | is echo echo : false

library(ggplot2 )

# Randomly generate data that acts as 30-day trailing unit sales.
today <- Sys.Date()
data <- data.frame(
  Date = today - 1:30,
  Sales = sample(75:100,30,replace = TRUE)
)


last <- data$Sales[length(data$Sales)]
previous <- data$Sales[length(data$Sales) - 1]
compared_to <- if (last == previous) {
  "constant"
   } else if (last > previous) {
    "higher"
   } else {
     " low "
   }

scatter <- ggplot(data = data,aes(x = Date,y = Sales)) +
   geom_point ( ) +
  ggtitle("Unit sales (30 days)") +
  theme_minimal()
hist <- ggplot(data = data,aes(y = Sales)) +
   geom_histogram(bin = 5 ) +
  ggtitle("Unit sale frequency (30 days)") +
  theme_minimal()
` ` `

This document summarizes recent sales information,produces some
plots,and composes an   email message containing the most important
detail .

The scatter plot showing recent sales information is included in
both the rendered document and the   email message.

` ` ` { r }
# is echo | is echo echo : false

scatter
` ` `

The histogram is only include in the render document .

` ` ` { r }
# is echo | is echo echo : false

hist
` ` `

: : : { .email }

: : : {.subject}
sales are `{r} compared_to`
: : :

This   email message has a dynamic subject and embeds the same
scatter plot that is in the rendered document.

` ` ` { r }
# is echo | is echo echo : false

scatter
` ` `

: : :