Quarto and Positron

Overview

This unit explains how to use Quarto within the Positron IDE.

Goals

Be able to create and render basic Quarto documents through Positron.

Reading

Quarto and Positron

Quarto documents are basically text documents. They have the file extension .qmd (Quarto Markdown). You can create and edit these files in any text editor, including Positron.

Creating Quarto documents with Positron

Start Positron. Then start a project (or open an existing one) as you learned in the Brief Intro to Positron course. Next, create a new file by going to File -> New File -> Quarto Document. A new tab opens with a basic Quarto document template.

We’ll talk more about what Quarto documents look like in the next unit. For now, let’s just create a simple Quarto document to see how it works in Positron. Delete the bit of text that’s there, and replace it with this text.


---
title: "Simple Quarto Example"
format: html
---

# This is a heading 

## This is a subheading

Here is text. **This is bold text.** 
Formatting follows the Markdown syntax.

## A code example

Here is a simple example demonstrating the integration of R code within the document.

```{r}
x <- seq(1, 10)
y <- x^2
plot(x,y)
```

The code is executed when the Quarto document is processed (rendered), and the resulting figure is automatically included in the output document.

Next, save the file in your project folder. You can name it anything, e.g. simple-example.qmd. The important part is to give it the .qmd ending to indicate that it’s a Quarto file.

Positron supports editing Quarto files in two ways. One is called Source, which is where you see the actual text with Markdown formatting. The other one is called Visual, which gives you a preview of how the document will look when rendered. You can switch between these two modes by clicking the buttons in the top right corner of the editor window. Give it a try.

If you do switch back and forth, you might notice that sometimes the formatting of the source changes slightly. This should not matter and you should always be able to switch back and forth between source and visual views.

Rendering

Once you have written your document and want to see the result, you can render it. Rendering is the name used by Quarto for turning your source document(s) (your .qmd files) into some other output, such as HTML, PDF or MS Word. The easiest way to do this is to click the Preview button at the top left of the editor window. Positron will execute the quarto preview command in the terminal (go there to see it). This both renders the document and opens the resulting file either inside the viewer in Positron or in your default software (e.g. a web browser for HTML output or MS Word for Word output).

Try this now. Click the Preview button. You should see the rendered document appear either in the viewer pane or in your web browser.

While it is convenient to press the Preview button in Positron, it’s good to know and be able to run Quarto directly. Let’s say you don’t want the preview and instead just render the file, i.e. create the output file (here HTML) without opening it.

You can do this by running Quarto through the terminal. Go to the terminal. It might still be busy from showing the preview. If you see something like “Listening on …” press Ctrl + C to stop it. You should then see the prompt, which ends with the > symbol. Now type the following command:

quarto render name-of-file.qmd

As long as you are in the right folder, the one where you saved the Quarto file to, this will create the output file (here HTML) in the same folder. You should see the file show up in the ‘Explorer’ view in Positron (the top icon on the left sidebar).

Customizing Quarto Settings in Positron

Positron comes with the Quarto extension pre-installed, providing seamless integration for Quarto document creation and rendering. You can change settings for Quarto as you learned previously in the Positron Extensions unit of the Brief Intro to Positron course.

Debugging and Troubleshooting

If you encounter issues when using Quarto, you will usually see an error message in the Terminal pane that explains what might be going wrong. Quite often, rendering fails if links are broken, code doesn’t run properly, or the YAML block is not properly formatted.

Summary

Quarto is nicely integrated into Positron, allowing you to create, edit, and render Quarto documents directly within the IDE.

Further Resources

Practice

Find a Quarto file somewhere online. Copy to your computer, open it in Positron, and render it.
Open the Quarto settings and change some of the options. Then create and render a new Quarto document and see if or how the changed settings affect the new document.

Overview

Goals

Reading

Quarto and Positron

Creating Quarto documents with Positron

Rendering

Customizing Quarto Settings in Positron

Debugging and Troubleshooting

Summary

Further Resources

Test yourself

Practice