Workflow

Positron/VS Code: open → edit → preview → render

Open

Save the document template in a working folder outside this teaching website. Keep the filename document-template.qmd for the commands below.

In Positron/VS Code, choose File → Open Folder. Open that folder, then click the .qmd file. Use the Source editor so you can edit the text and code directly.

Edit

Change the title and author between the --- lines at the top. Write text outside the Python cells and code inside them.

Save with Cmd+S on macOS or Ctrl+S on Windows. Edit the .qmd, not the generated HTML or PDF.

Opening and editing in Positron · VS Code

Run Python

Click Run Cell above a Python cell. Run earlier cells first when their imports or variables are needed.

Editor	Where to look
Positron	Console for text output; Plots for graphs.
VS Code	Jupyter Interactive window for code output.

Running a cell does not update the document preview. Rendering runs the enabled cells for you; you do not need to run them manually first.

Do not run the template’s graph or table cell until you have supplied its data. The eval: false option skips that cell during rendering.

Python execution · Code-cell options

Create tables from Python output

Use the automatic-table example to calculate summary statistics and display them as a numbered table. Copy its complete Python cell into your .qmd file; the example includes data so it runs immediately.

When you use your own data, define the DataFrame before the table cell. For the downloadable template’s existing table cell, change #| eval: false to #| eval: true once df exists. Add #| echo: false if you want to show only the table in the finished document.

Save and render again whenever the data or calculations change. Quarto regenerates the table, caption, and cross-references for HTML or PDF output.

Preview

Open the Command Palette: Cmd+Shift+P on macOS or Ctrl+Shift+P on Windows. Choose Quarto: Preview Format, then HTML.

After editing and saving, run Quarto: Preview again. The shortcut is Cmd+Shift+K on macOS or Ctrl+Shift+K on Windows.

For automatic updates when you save:

Editor	Setting
Positron	Tick Render on Save in the document toolbar.
VS Code	Open Settings, search for `quarto.render`, and enable Render on Save.

Positron preview · VS Code preview

Render

Save the .qmd. Open Terminal → New Terminal in the folder containing it. These are terminal commands, not Python code.

Create HTML:

quarto render document-template.qmd --to html

Create PDF:

quarto render document-template.qmd --to pdf

For a standalone document, the output is saved beside the source as document-template.html or document-template.pdf. PDF output needs the LaTeX installation.

Alternatively, use Quarto: Render Document in the Command Palette and select a format.

Render command

Preview from the terminal

quarto preview document-template.qmd --to html

Leave the command running while you edit and save. Press Ctrl+C in that terminal to stop previewing, on either macOS or Windows.

Terminal workflow

Check Python

Select the Python installation you normally use (or the one you just installed) in Positron’s Interpreter picker, or through Python: Select Interpreter in VS Code. In the terminal, check:

quarto check jupyter

The editor’s interactive Python and the Python used for rendering must have the packages your document needs. Selecting an interpreter in the editor does not by itself guarantee that every terminal uses it.

Installation · Quarto’s Python configuration

--- title: "Workflow" subtitle: "Positron/VS Code: open → edit → preview → render" --- # Open Save the [document template](downloads/document-template.qmd) in a working folder outside this teaching website. Keep the filename `document-template.qmd` for the commands below. In Positron/VS Code, choose **File → Open Folder**. Open that folder, then click the `.qmd` file. Use the **Source** editor so you can edit the text and code directly. # Edit Change the title and author between the `---` lines at the top. Write text outside the Python cells and code inside them. Save with **Cmd+S** on macOS or **Ctrl+S** on Windows. Edit the `.qmd`, not the generated HTML or PDF. [Opening and editing in Positron](https://quarto.org/docs/get-started/hello/positron.html) · [VS Code](https://quarto.org/docs/get-started/hello/vscode.html) # Run Python Click **Run Cell** above a Python cell. Run earlier cells first when their imports or variables are needed. | Editor | Where to look | |:---|:---| | Positron | Console for text output; Plots for graphs. | | VS Code | Jupyter Interactive window for code output. | **Running a cell does not update the document preview.** Rendering runs the enabled cells for you; you do not need to run them manually first. Do not run the template's graph or table cell until you have supplied its data. The `eval: false` option skips that cell during rendering. [Python execution](https://quarto.org/docs/computations/python.html) · [Code-cell options](https://quarto.org/docs/computations/execution-options.html) # Create tables from Python output Use the [automatic-table example](sessions/01-writing-with-quarto.qmd#automatic-tables) to calculate summary statistics and display them as a numbered table. Copy its complete Python cell into your `.qmd` file; the example includes data so it runs immediately. When you use your own data, define the DataFrame before the table cell. For the downloadable template's existing table cell, change `#| eval: false` to `#| eval: true` once `df` exists. Add `#| echo: false` if you want to show only the table in the finished document. Save and render again whenever the data or calculations change. Quarto regenerates the table, caption, and cross-references for HTML or PDF output. # Preview Open the Command Palette: **Cmd+Shift+P** on macOS or **Ctrl+Shift+P** on Windows. Choose **Quarto: Preview Format**, then **HTML**. After editing and saving, run **Quarto: Preview** again. The shortcut is **Cmd+Shift+K** on macOS or **Ctrl+Shift+K** on Windows. For automatic updates when you save: | Editor | Setting | |:---|:---| | Positron | Tick **Render on Save** in the document toolbar. | | VS Code | Open Settings, search for `quarto.render`, and enable **Render on Save**. | [Positron preview](https://quarto.org/docs/get-started/hello/positron.html#basic-workflow) · [VS Code preview](https://quarto.org/docs/tools/vscode/index.html#render-and-preview) # Render Save the `.qmd`. Open **Terminal → New Terminal** in the folder containing it. These are terminal commands, not Python code. **Create HTML:** ```bash quarto render document-template.qmd --to html ``` **Create PDF:** ```bash quarto render document-template.qmd --to pdf ``` For a standalone document, the output is saved beside the source as `document-template.html` or `document-template.pdf`. PDF output needs the [LaTeX installation](installation.qmd#install-tinytex-for-pdfs). Alternatively, use **Quarto: Render Document** in the Command Palette and select a format. [Render command](https://quarto.org/docs/tools/positron/#render-command) # Preview from the terminal ```bash quarto preview document-template.qmd --to html ``` Leave the command running while you edit and save. Press **Ctrl+C** in that terminal to stop previewing, on either macOS or Windows. [Terminal workflow](https://quarto.org/docs/get-started/hello/text-editor.html) # Check Python Select the Python installation you normally use (or the one you just installed) in Positron's **Interpreter picker**, or through **Python: Select Interpreter** in VS Code. In the terminal, check: ```bash quarto check jupyter ``` The editor's interactive Python and the Python used for rendering must have the packages your document needs. Selecting an interpreter in the editor does not by itself guarantee that every terminal uses it. [Installation](installation.qmd#install-the-python-packages) · [Quarto's Python configuration](https://quarto.org/docs/computations/python.html)