Publish a Quarto document with R to Connect Cloud

Publish a Quarto document with R to Connect Cloud from GitHub, Positron or VS Code, RStudio, or the command line. Compare methods and steps.

Skip the guide and publish the sample document

In this guide, you publish a Quarto document that uses R to Connect Cloud and get a URL you can share. You can publish from GitHub, from Positron or VS Code, from RStudio, or from the command line. The sample document is a dashboard of recent earthquakes in New Zealand, built from live data from the GeoNet API.

A Quarto dashboard with value boxes for hours since the last earthquake and earthquakes in 24 hours, a table of recent earthquakes, and a map — The sample Quarto dashboard previewed locally

The source code is available in the examples-quarto-r repository.

Getting started

Whichever method you choose, you need the following:

A Connect Cloud account.
A Quarto document that uses R. This guide uses the sample document, which has a main file (Connect Cloud calls it the primary file) named report.qmd.
If you publish from GitHub, a renv.lock or manifest.json file that lists the R packages your content uses. Posit Publisher and push-button publishing do this for you.
Quarto installed, to preview the document on your computer.

View the sample document code

Save this file as report.qmd.

report.qmd

---
title: Recent Earthquakes in Aotearoa New Zealand
author: Of Weak Intensity or Greater
format: 
  dashboard:
    orientation: columns
    theme: yeti
---

```{r}
#| message: false
library(tidyverse)
library(httr2)
library(sf)
library(leaflet)
library(gt)
```

```{r}
# Get data from GeoNet
# MMI = 3, weak or above
req <- request("https://api.geonet.org.nz/quake?MMI=3") |> 
  req_headers("Accept"="application/vnd.geo+json")
resp <- req_perform(req)
recent_quakes <- resp |> 
  resp_body_string() |> 
  st_read(quiet = TRUE)
```

```{r}
# Prettier times and dates
recent_quakes <- recent_quakes |> 
  arrange(desc(time)) |> 
  mutate(
    time = force_tz(time, "Pacific/Auckland"),
    pretty_time = format(time, "%I:%M %p"),
    days_ago = today(tzone = "Pacific/Auckland") - date(time),
    days_ago = case_when(
      days_ago == 0 ~ "Today",
      days_ago == 1 ~ "Yesterday",
      TRUE ~ paste0(days_ago, " days ago")
    )
  )
now_nz <- now(tzone = "Pacific/Auckland")
last_24 <- recent_quakes |> filter(time > (now_nz - hours(24)))
n_24 <- nrow(last_24)
hours_last <- round(difftime(now_nz, recent_quakes$time[1], units = "hours"))
```

```{r}
mag_pal <- colorBin("inferno", domain = 1:8, bins = c(0:5, 8))

quake_map <- recent_quakes |> 
  leaflet() |> 
  addCircleMarkers(
    color = ~ mag_pal(magnitude),
    stroke = FALSE,
    fillOpacity = 0.5,
    radius = ~ scales::rescale(sqrt(magnitude), c(1, 10)),
    label = ~ paste(
      date(time), pretty_time, "<br/>",
      "Magnitude:", round(magnitude, 1), "<br/>", 
      "Depth:",  round(depth), " km"
      ) |> map(html),
    labelOptions = c(textsize = "15px")) |> 
  addLegend(title = "Magnitude", colors = mag_pal(0:5), labels = c("<1", 1:4,">5")) |> 
  addTiles("http://services.arcgisonline.com/arcgis/rest/services/Canvas/World_Light_Gray_Base/MapServer/tile/{z}/{y}/{x}", options = tileOptions(minZoom = 5, maxZoom = 10)) 
```

```{r}
mag_hist <- recent_quakes |> 
  ggplot(aes(x = magnitude)) +
  geom_histogram()
```

```{r}
timeline <- recent_quakes |> 
  ggplot(aes(x = time, y = 0)) +
  geom_point()
```


```{r}
# Create n most recent table
n <- 10
top_n <- recent_quakes |> 
  slice(1:n) |> 
  as.data.frame() |> 
  select(magnitude, days_ago, pretty_time, locality, depth) 

top_n_table <- top_n |> 
  gt() |> 
  cols_label(
    days_ago = "",
    locality = "Location",
    magnitude = "Magnitude",
    depth = "Depth",
    pretty_time = ""
  ) |> 
  fmt_integer(
    columns = depth, 
    pattern = "{x} km"
  ) |> 
  fmt_number(
    columns = magnitude,
    decimals = 1
  ) |> 
  data_color(
    columns = "magnitude",
    fn = mag_pal
  ) |>
  tab_header(
    title = md("**Last 10 Earthquakes**")
  ) |> 
  tab_source_note(
    source_note = md(paste("Retrieved from the [GeoNet API](https://api.geonet.org.nz/) at", format(now_nz, "%Y/%m/%d %H:%M %Z")))
  )
```

## Column

### Row 

```{r}
#| component: valuebox
#| title: Hours since last earthquake
list(
  icon = "stopwatch",
  color = "primary",
  value = as.numeric(hours_last)
)
```

```{r}
#| component: valuebox
#| title: Earthquakes in the last 24 hours
list(
  icon = "activity",
  color = "secondary",
  value = n_24
)
```

### Row

```{r}
top_n_table
```


## Column

```{r}
#| title: 100 Most Recent Earthquakes
quake_map
```

To preview the document before you publish, click Render in RStudio, or run Quarto from the folder that contains report.qmd:

Terminal

quarto preview report.qmd

Note

You can also publish a Quarto project by using its _quarto.yml file as the primary file, or a document you already rendered (for example, report.html). See Quarto.

Choose a deployment method

Method	When to use it	Jump to
GitHub	Your code is on GitHub and you want it to update when you push (public repositories only on free accounts)	Deploy from GitHub
Posit Publisher	You work in Positron or VS Code and do not use GitHub	Deploy from Positron or VS Code
Push-button publishing	You work in RStudio and do not use GitHub	Deploy from RStudio
rsconnect	You want to deploy from the R console or automate deployments	Deploy from the command line
Quarto CLI	You want to publish from a terminal with `quarto publish`	Deploy from the command line

For more on how these methods differ, see Publishing.

Deploy from GitHub

Use this method when your document’s code is in a GitHub repository and you want changes you push to publish automatically. On a free account, your repository must be public, so anyone can see your code.

Create a manifest.json file by running this in the R console from the folder that contains report.qmd:
```
rsconnect::writeManifest()
```
Commit report.qmd and manifest.json, then push your document to a GitHub repository.
Sign in to Connect Cloud.
Click Publish at the top of your Home page. If this is your first time publishing, Connect Cloud prompts you to install the GitHub App, which lets Connect Cloud read your repository.
Select Quarto.
Select your repository.
Check that Branch is the branch that has your content, usually main.
Select report.qmd as the Primary file.
Leave Automatically publish on push on if you want Connect Cloud to update what you published each time you push to this branch. Turn it off to update only when you choose.
Click Publish.

Result: Connect Cloud shows a log of the install steps while it deploys. When it finishes, your document is live at an address like https://[content-id].share.connect.posit.cloud, where [content-id] is a unique identifier that Connect Cloud picks. You can set a custom name to change the URL.
Update or redeploy: Commit and push to the connected branch and Connect Cloud republishes automatically. If you turned off automatic publishing, click Republish on the content’s card on your Home page. See Republishing.

For all options, see Publish from GitHub.

Deploy from Positron or VS Code

Use this method when you work in Positron or VS Code and want to publish your document directly. Positron includes the Posit Publisher extension. In VS Code, install it from the marketplace first.

Open your project folder in Positron, or in VS Code with Posit Publisher installed.
Click the Posit Publisher icon in the Activity Bar.
Next to CREDENTIALS, click + and select Posit Connect Cloud. A credential is a saved connection to your Connect Cloud account. Your browser opens.
In your browser, check that the Authorize Access code matches the code in Positron or VS Code. Then click Continue and Authorize.
Return to Positron or VS Code and accept or change the name for this credential. Do this once.
Click the + next to Deployments. If Posit Publisher asks which file to publish, select report.qmd.
Enter a title for your content, then select the credential you just added.
Under PROJECT FILES, check that the list includes report.qmd. Connect Cloud uploads only the files in this list.
Click Deploy Your Project.

Result: A success message appears in the lower right of Positron or VS Code. Click View Content in the extension to open the document on Connect Cloud. Its address has the form https://[content-id].share.connect.posit.cloud, where [content-id] is unique to your document.
Update or redeploy: Save your changes, open Posit Publisher, select the previous deployment, and click Deploy Your Project again. Keep the .posit folder in your project. It remembers which Connect Cloud content this project publishes to, so the next deploy updates the same content instead of creating a new one.

For the configuration file, multiple deployments per project, and troubleshooting, see Publish from your IDE.

Deploy from RStudio

Use this method when you work in RStudio and want to publish your document directly with push-button publishing.

Open report.qmd in RStudio and click Render.
Click Publish in the toolbar.
Follow the prompts to connect your Connect Cloud account and publish.

Result: RStudio opens your document on Connect Cloud.
Update or redeploy: Render the document again and click Publish.

For setup instructions and supported content types, see Publish from your IDE and the RStudio IDE publishing documentation.

Deploy from the command line

Use this method to script deployments. Run the rsconnect package from the R console, or run the Quarto CLI from a terminal.

Use the rsconnect package

Run these commands from an R session with the rsconnect package. You do not need a manifest.json or renv.lock file for this method.

Install the package.
```
install.packages("rsconnect")
```
Add your Connect Cloud account. Your browser opens for you to authorize access.
```
rsconnect::connectCloudUser()
```
Deploy the document.
```
rsconnect::deployDoc("report.qmd")
```

If you have several accounts configured, rsconnect asks which one to use.

Result: A successful deployment opens your browser to your content’s page on Connect Cloud.
Update or redeploy: Run rsconnect::deployDoc("report.qmd") again.

For noninteractive credentials and other options, see Publish from your console or terminal.

Use the Quarto CLI

Run these commands from a terminal. This requires Quarto version 1.9 or higher.

From your project folder, run this command with the name of your document:
```
Terminal
```
```
quarto publish report.qmd
```
Select Posit Connect Cloud from the list of providers.
When your browser opens, sign in to your Posit account and authorize access. Do this the first time only.

Result: Quarto renders your content and deploys it to Connect Cloud. It records the content identifier and URL in a _publish.yml file in your project. The file does not store credentials, so you can check it into version control.
Update or redeploy: Run quarto publish report.qmd again. Quarto uses _publish.yml to update the same content.

For more information, see Publish from your console or terminal and the Quarto publishing documentation.

After you deploy

Common things to set up next. They work the same however you deployed your document:

Passwords and API keys: Store them as secret variables, not in your code. Add them under Variables in content settings, or during publishing. Read them with Sys.getenv("NAME").
Access and sharing: Control who can view your document in Sharing.
Scheduling: On paid plans, schedule your document to republish at set times, for example, to refresh data each day.
Custom name and domain: Change the document’s URL with a custom name or a custom domain.
Upload size limit: The upload size limit applies when you upload your project files from your editor, the R console, or the command line.

Troubleshooting

Missing package error: Re-run rsconnect::writeManifest() so manifest.json lists every package your document loads, then commit it and republish.
Repository not listed: Confirm that the GitHub App has access to it.
Document renders locally but not on Connect Cloud: Check that every file the document reads is committed or included in the upload, and that your dependency file matches the packages you use locally.

If your deployment still fails, read the log that Connect Cloud shows while it deploys and look for the first error. You can also try Error Assist, which gives guidance based on your log output.