Previewing

q2 preview opens your document or website in a browser and keeps it up to date as you edit. It has two modes.

	`q2 preview` (default)	`q2 preview --static`
What runs	A live session: pages render in the browser as you type	A real `q2 render` to disk, served by a plain static server
On save	The page updates in place; open menus, scroll position and math survive	The changed page re-renders; the browser reloads
What you see	The page being edited	Exactly what `q2 render` produces, including the sitemap, listings, search index and scripts
Code cells	Executed on the server, re-executed on request	Executed only for pages you open (see below)
Best for	Writing and editing	Checking the finished site, or a workflow like Quarto 1’s `quarto preview`

The default preview

Terminal

q2 preview                # the project in the current directory
q2 preview posts/one.qmd  # open on a specific page
q2 preview notes.qmd      # a document outside any project

The browser opens automatically. Edits appear within a fraction of a second without rebuilding the page, so JavaScript state is preserved across edits. See the --help text for the flags that control the port, the browser, and live sharing.

Typst documents

A page whose format is typst or pdf shows its PDF in the preview, in a pdf.js viewer, and recompiles it shortly after you stop typing. A compile that fails keeps the last good PDF on screen under an error banner. When you reached the page from another one, a Back button at the left of the viewer’s toolbar returns to it. In a book project the preview shows the page you are on, not the whole book.

A page that sets output-ext to something other than pdf (typst source, say) has no PDF to show, so it keeps the “no live preview” notice.

The compile runs the typst on your PATH, and writes into .quarto/preview-out/ under the project (git-ignored, swept at startup), so the project directory must be writable. This view has no Download as menu; that is part of the editor UI below.

Render options in the live viewer

q2 preview --to FORMAT, -M KEY:VALUE and --profile NAME work as for q2 render (Render options); for instance q2 preview book/ --to typst shows PDF panes. Notes:

They are refused with --ui editor (the editor has its own settings), --join and --no-project.
--to and -M are applied to the page preview, the PDF pane and the downloads. They do not reach code execution.
-M book-scope:... is ignored (a startup notice says so): the viewer renders one page at a time, and the PDF pane always asks for the chapter.
--profile works as QUARTO_PROFILE does: the PDF pane, downloads and the server’s project settings honor it, but the page you edit is rendered in the browser from the synced project, which has no profile files, so the html preview ignores it (a startup notice says so).
--to typst with a page that sets output-ext: typ passes the check but has no live preview.
With --share, the -M values and --to are sent to every guest’s browser. Do not put secrets in -M.

The editor UI

Terminal

q2 preview --ui editor    # the quarto-hub editor, served by q2

--ui editor serves the same editor as quarto-hub: a source editor next to the preview, with a Download as menu and an Import button. Everything the browser version of quarto-hub does in the browser, the editor UI asks q2 to do with the pandoc and typst on your machine:

Download as produces Word (.docx), OpenDocument (.odt), PowerPoint (.pptx), EPUB, Typst source (.typ) and PDF. The file is rendered from what is in the editor, saved or not. Code-cell output is included, Word comments and tracked changes carry the author’s name, and a notice says how many code cells were not executed.
Typst documents (format: typst or format: pdf) show the PDF in the preview pane and re-render it as you type. A render that fails keeps the last good PDF on screen under an error banner.
Books. On a chapter of a book project, the Typst source, PDF and EPUB entries come in pairs: Download book as renders the whole book into one file named for the book (My-Book.pdf), and This chapter only renders just the page you are on. (Word, OpenDocument and PowerPoint have no whole-book output, so they always download the page.) A page that is not listed in the book’s chapters downloads on its own, with a notice (Q-5-41) saying why it is not the book.
Import reads docx, odt, rtf, epub and pptx files into a new document, with its images stored next to it in <name>_media/. The result is created in the editing session; it reaches your files on disk only when you started q2 preview with --allow-edit, as for any other edit. Images larger than 10 MB are not stored, as in quarto-hub.

These need pandoc on your PATH, and typst for Typst and PDF output. When one is missing, the preview pane or the download says so (Q-20-1, Q-20-2, Q-21-1) rather than offering nothing. Typst packages that q2 does not carry (@preview/..., including the book template’s) are fetched from the Typst package registry, so a first PDF of a document that uses one needs network access.

The PDF you get here and the PDF quarto-hub makes in the browser are both correct but not byte-for-byte identical. quarto-hub compiles with a pinned Typst and a bundled font set; q2 preview uses the typst installed on your machine, your system fonts and real Typst packages. Line breaks and font fallbacks can differ between the two.

The typst source download is the bare .typ file; images are not bundled with it.

What a book download does and does not include

Only the page open in the editor is rendered from its editor text. Every other chapter is read from disk, so unsaved edits to those are not in the download (and, without --allow-edit, edits made in the editor are never on disk).
Pre-render and post-render scripts do not run, and the book’s own output-ext is ignored: Typst source is a .typ and PDF is a .pdf, whatever the project says.
Code cells are not executed for a download. Output that was recorded while you edited is included; a notice counts the cells that had none. A chapter that embeds a cell from another chapter needs that cell’s executed output, so downloading that book whole can fail; the chapter alone still downloads.
The project’s own _book/ directory and render manifests are not touched.
One book download per project runs at a time. A second request while one is running is answered “the preview server is busy”; try again when the first finishes. A small book takes a second or two; a large one can take much longer, and cancelling takes effect between chapters.

Static preview

Terminal

q2 preview --static                # render the project, serve it, watch for changes
q2 preview --static posts/one.qmd  # the whole project, opened on that page
q2 preview --static notes.qmd      # a lone document

--static first renders everything to disk, exactly as q2 render does, then serves the output directory (_site for a website) on a local port and opens the browser. It then watches your files:

Saving a page re-renders that page (and any page that depends on it, such as a listing that includes it) and reloads the browser, opening the page you changed.
Saving _quarto.yml, a _metadata.yml, a stylesheet, an image, an extension file, or anything else that is not a page re-renders the whole project and reloads the browser in place.
A save that fails to render leaves the previous output in place and shows the error in a panel at the bottom of the page. Fix the file and the page reloads.

Each re-render is a real render: pre-render and post-render scripts run, and the output directory is what you would publish.

Typst and PDF

--static also serves format: typst output. The rendered .pdf opens in a pdf.js viewer rather than the browser’s own PDF viewer, and the viewer reloads when a re-render finishes, keeping your page and zoom. For a book project, --static renders and serves the whole book, and a saved chapter rebuilds the whole book. The viewer needs typst on your PATH, like the render itself. --static does not serve other non-HTML formats (docx, pptx, epub): they are refused once, before anything renders. A render that writes nothing shows its diagnostics in the browser instead of an empty page.

Flags

Flag	Meaning
`--no-watch`	Render once and serve; never re-render
`--no-navigate`	After a re-render, reload the current page instead of opening the page that changed
`--to FORMAT`	The output format, as `q2 render --to`. Only `html`, `revealjs` and `typst` can be served
`-M KEY:VALUE`	Metadata for the whole session, as `q2 render -M`
`--profile NAME`	The active profile(s), as `q2 render --profile`
`--port N`, `--host H`	Where to listen. Default: a free port on `127.0.0.1`
`--no-browser`, `--browser APP`	Do not open a browser, or open a specific one

--to, -M and --profile mean here what they mean for q2 render (Render options). -M book-scope:chapter on a book exits with Q-5-47, because the flag is fixed for the session and a whole book can never be one chapter.

The live-session flags (--share, --allow-edit, --ui, --join) do not apply to static mode.

Code execution

A static preview does not execute every page’s code up front: a site with many Jupyter or knitr pages would take a long time to start. Pages whose code has not run are served with their code cells shown as source, and the first time you open such a page it is executed and reloaded. Pages you have opened stay executed through later re-renders.

To never execute code in a preview, set this in _quarto.yml:

_quarto.yml

preview:
  engine: off

This is the same key the default preview uses.

Defaults in `_quarto.yml`

Quarto 1’s project: preview: keys set the defaults for static mode; command-line flags override them.

_quarto.yml

project:
  type: website
  preview:
    port: 4321
    host: 127.0.0.1
    browser: false
    watch-inputs: false
    navigate: false

The timeout and serve keys from Quarto 1 are not supported. They are reported once at startup and otherwise ignored.