Text Editors

Overview

If you are editing plain markdown documents (with no embedded computations) you may want to use your favorite text editor (Vim, Emacs, Sublime, etc.) to author Quarto documents. This articles provides some guidance on the optimal workflow when using text editors with Quarto.

Note that if you are using either the Jupyter or Knitr computational engine you will likely be better off using JupyterLab or VS Code (for .ipynb notebooks) or RStudio (for .qmd documents) as these environments provide code-completion, incremental cell execution, and other useful tools for working with executable code.

Workflow

The ideal workflow for authoring Quarto markdown documents is to run the quarto preview command from within a terminal:

quarto preview document.md

The document will be rendered and a web browser with a “live preview” opened. Position this browser so that you can see it as you edit and save the document:

Two application windows arranged side by side. A Quarto document that contains the contents of the Welcome page of this website is open on the right. The contents of this document are rendered in a web browser by Quarto in the window on the right.

Every time you save the preview will be automatically updated. You can use quarto preview for both HTML and PDF output.

Note that if you are authoring a book or website you can also use quarto preview on the project directory, which will create a live preview for the entire project.

Render without Preview

You can render a document (or group of documents) without previewing them using the quarto render command:

quarto render document.md

Use the --to argument to render to different formats:

quarto render document.md --to docx

File Extension

You’ll likely find that it’s easier to use the .md file extension (rather than .qmd) when working with plain markdown documents. This enables you to take advantage of existing behaviors associated with .md in your text editor configuration (you can certainly also modify your editor configuration to recognize .qmd).

Note that if you end up at some point including embedded computations in your document you should at that point change the extension to .qmd (and as discussed above possibly migrate to using a tool that has more built-in tools for working with executable code).