VS Code

Overview

Quarto can render Jupyter notebooks represented as plain text (.qmd) or as a normal notebook file (.ipynb). The Quarto VS Code Extension includes many tools that enhance working these documents, including:

  • Integrated render and preview for Quarto documents.
  • Syntax highlighting for markdown and embedded languages
  • Completion and diagnostics for YAML options
  • Completion for embedded languages (e.g. Python, R, Julia, etc.)
  • Commands and key-bindings for running cells and selected lines.
  • Live preview for LaTeX math as well as Mermaid and Graphviz diagrams

The Quarto extension integrates directly with the Jupyter, R, and Julia extensions. For example, here the Quarto extension runs a Python cell and shows contextual help for Python functions:

Screen shot of VS Code editor with three vertical sections. The leftmost includes the file explorer, and quarto help. The second pane is the source code for a quarto file with python code. The third is interactive with Python running and output of the code cells shown.

Installation

You can install the Quarto extension from the VS Code Extension Marketplace, the Open VSX Registry or directly from a VISX extension file.

Render and Preview

The Quarto VS Code extension includes commands and keyboard shortcuts for rendering Quarto documents (both standalone and within websites or books). After rendering, quarto preview is used behind the scenes to provide a preview pane within VS Code alongside your document:

Two windows arranged side by side. The window on the left is a qmd file opened in VSCode. The contents of this document are the same as the first part of the Getting Started: Welcome section of this website. The contents of this document are rendered by Quarto in the window on the right.

To render and preview, execute the Quarto: Render command. You can alternatively use the Ctrl+Shift+K keyboard shortcut, or the Render button at the top right of the editor:

The top of the Visual Studio code editor. The right side of the editor tab area includes a Render button.

Note that on the Mac you should use Cmd rather than Ctrl as the prefix for all Quarto keyboard shortcuts.

Additionally, there are commands available to render specific formats. Here is a complete list of the supported render commands:

  • Quarto: Render
  • Quarto: Render HTML
  • Quarto: Render PDF
  • Quarto: Render Word

The Quarto: Render command renders the default format of the currently active document. The other commands render specific formats (regardless of the document’s default format). The Ctrl+Shift+K keyboard shortcut will re-execute the most recently executed render command.

Embedded preview is currently supported for HTML and PDF based formats (including revealjs and beamer slideshows). However, for Word and other formats you need to use an appropriate external program to preview the output.

External Preview

If you prefer to use an external browser for preview (or have no preview triggered at all by rendering) you can use the Preview Type option to specify an alternate behavior:

VS Code settings interface with 'quarto preview type' entered into the search bar. User settings reveals Quarto > Render: Preview Type, with a dropdown to select location for document preview after render. The default, internal, is selected, which previews using a side-by-side panel in VS Code. The other two options in the dropdown are external and none.

Code Cells

There are a variety of tools that make it easier to edit and execute code cells. Editing tools include syntax highlighting, code folding, code completion, and signature tips:

A Quarto document in VS Code with a python code cell. There is a code completion helper active in the python cell.

For Python, R, and Julia cells, commands are available to execute the current cell, previous cells, or the currently selected line(s). Cell output is shown side by side in the Jupyter interactive console:

VS Code with two panes open, vscode.qmd source code on the right, and the interactive output of that code shown in a second pane on the left.

Here are all of the commands and keyboard shortcuts available for executing cells:

Quarto Command Keyboard Shortcut
Run Current Cell ⇧⌘ Enter
Run Selected Line(s) ⌘ Enter
Run Next Cell ⌥⌘ N
Run Previous Cell ⌥⌘ P
Run All Cells ⌥⌘ R
Run Cells Above ⇧⌥⌘ P
Run Cells Below ⇧⌥⌘ N

Enhanced features for embedded languages (e.g. completion, code execution) can be enabled by installing the most recent version(s) of these extensions:

Note that you can quickly insert a new code cell using the Ctrl+Shift+I keyboard shortcut.

Contextual Assistance

Execute the Quarto: Show Assist Panel command to show a panel in the sidebar that shows contextual assistance depending on the current cursor location:

  1. Help/documentation is shown when editing code
  2. A realtime preview of equations is shown when editing LaTeX math
  3. Thumbnail previews are shown when your cursor is located on a markdown image.

For example, below help on the matplotlib plot() function is shown automatically when the cursor is located on the function:

Screenshot of VS Code editor with three vertical sections. The leftmost includes the file explorer, and quarto help. The second pane is the source code for a quarto file with python code. The third is interactive with Python running and output of the code cells shown.

Live Preview

While editing LaTeX math or Mermaid and Graphviz diagrams, click the Preview button above the code (or use the Ctrl+Shift+L keyboard shortcut) to open a live preview which will update automatically as you edit.

Here we see a preview of the currently edited LaTeX equation displayed in the Quarto assist panel:

Quarto document open in VS Code with a LaTeX equation shown in the 'Quarto Equation' section of the panel to the left of the document.

Here we see a Graphviz diagram preview automatically updated as we edit:

A Quarto document being edited in Visual Studio Code, with a live preview of the currenly edited diagram shown in a pane to the right

YAML Intelligence

YAML code completion is available for project files, YAML front matter, and executable cell options:

Quarto document with YAML being edited. Next to the cursor code completion helper is open showing YAML options beginning with the letters preceding the cursor ('co').

If you have incorrect YAML it will also be highlighted when documents are saved:

Quarto document YAML metadata with an incorrect option underlined in red.

Note that YAML intelligence features require version 0.9.44 or later of the Quarto CLI.

Code Snippets

Code snippets are templates that make it easier to enter repeating code patterns (e.g. code blocks, callouts, divs, etc.). Execute the Insert Snippet command within a Quarto document to insert a markdown snippet:

Quarto document with dropdown 'Select a snippet' dropdown, the first item (bold - insert bold text) is selected.

Document Navigation

If you have a large document use the outline view for quick navigation between sections:

Quarto document with outline view shown in left-hand panel. The outline shows the section headers of the quarto documents.

You can also use the Go to Symbol in Editor command or keyboard shortcut Ctrl+Shift+O for type-ahead navigation of the current document’s outline.

Use the Go to File command Ctrl+P to navigate to other files and the Go to Symbol in Workspace command Ctrl+T for type-ahead navigation to all headings in the workspace:

Quarto document in VS Code with command pallete open showing the files in the project with the entered term, 'margin'.

Notebook Editor

In addition to editing Quarto document as plain-text .qmd files, you can also use the VS Code Notebook Editor to author .ipynb notebooks that are rendered with Quarto. Next we’ll review the basics of editing .ipynb notebooks for use with Quarto.

YAML Front Matter

The first cell of your notebook should be a Raw cell that contains the document title, author, and any other options you need to specify. Note that you can switch the type of a call to Raw using the cell type menu at the bottom right of the cell:

The top section of an ipynb file open in VSCode. There is a Raw cell containing yaml front matter.

In this example we specify that we want code to appear collapsed by default. There are YAML options to control many other aspects of document rendering. See the documentation on Authoring and Output Formats for additional details.

Markdown Cells

Here’s the underlying code for the markdown cell:

A snippet of an ipynb document containing a Markdown cell. The cell contains some text written in Markdown.

Note that a Quarto cross-reference (@fig-polar) is included in the markdown. Any valid Pandoc markdown syntax can be included in markdown cells.

Output Options

Quarto uses leading comments with a special prefix (#|) to denote cell options. Here we specify the label and fig-cap options so that the plot generated from the cell can be cross-referenced.

A snippet of a JupyterLab document containing a code cell. At the top of cell, before the code, are the Quarto chunk options '#| label: fig-polar' and '#| fig-cap: A line plot on a polar axis.'

Note that options must appear at the very beginning of the cell. As with document front-matter, option names/values use YAML syntax.

There are many output options available, including options to optionally hide code, warnings, and/or output. See the documentation on Output Outputs for additional details.

Cell Execution

Note that when rendering an .ipynb Quarto will not execute the cells within the notebook by default (the presumption being that you already executed them while editing the notebook). If you want to execute the cells you can pass the --execute flag to render:

quarto render notebook.ipynb --execute

You can also specify this behavior within the notebook’s YAML front matter:

---
title: "My Notebook"
execute: 
  enabled: true
---

There are many other execution options available (e.g. to control caching, optimizing kernel start-up time, etc.). Learn more about these options in Execution Options.

Converting Notebooks

You can convert between .ipynb and .qmd representations of a notebook using the quarto convert command. For example:

quarto convert basics-jupyter.ipynb
quarto convert basics-jupyter.qmd

See quarto convert help for additional details on converting notebooks.