6.7 Render Quarto

Rendering the whole website is slow. When you are editing a new section/page, you may want to edit as a standalone webpage and when you are finished, you add the qmd file to the _quarto.yml file index.

Difference btw a standalone webpage from a component of a qmd project

  • Standalone webpage: include yaml at the header of the file.

    Fast compile and rendering. ✅

  • A component of qmd project: added to the file index, no yaml needed, format will automatically apply.

    Slow, need to render the whole qmd project in order to see your change.

In terminal

This will provide live preview of the document in your web browser. Newest changes will be reflected while you edit the document. ✅

  • Render a Quarto document to HTML using the command line:

    $quarto render 0304-Quarto.Rmd --to html

  • Quarto Preview: display output in the external web browser.

    $ quarto preview 0304-Quarto.Rmd # all formats
$ quarto preview 0304-Quarto.Rmd --to html # specific format
    • Note that quarto render can be used to Rmd files too.
    • Run quarto preview help to see its complete syntax.

  • You can also render a Quarto project using:

    $quarto render --to html

quarto preview [file] [args] first provide file name, then additional arguments.

Supported arguments:

  • --port Suggested port to listen on (defaults to random value between 3000 and 8000).

  • --host Hostname to bind to (defaults to 127.0.0.1)

  • --no-browser Use internal viewer, do not open external browser.

  • --no-watch-inputs flag specifically prevents Quarto from automatically re-rendering the output when changes are detected in your input source files (e.g., .qmd files). This means that if you edit and save your .qmd file, the preview in your browser will not automatically update.

    To see changes in the preview when using this flag, you would need to manually stop the quarto preview process and restart it, or explicitly trigger a re-render using quarto render.

    Even when using this flag, Quarto will still print the message “Watching file for changes.” This means that Quarto is still watching CSS files and _quarto.yml for changes, but not the main input files.

quarto preview [file] --port 7200 Previewing website using a specific port. This is useful when your want to preview multiple documents simultaneously.

The default “internal” viewer in VS Code opens only one document at a time. Can use Simple Browser Multi Extension to open multiple internal browsers in VS Code.

Steps:

  1. Install Simple Browser Multi Extension.

  2. Use command quarto preview 0304-Quarto.Rmd --port 7200 in terminal to start live preivew. This will open the preview in your external web browser.

    If you don’t want automatic re-rendering when you save the file, add --no-watch-inputs flag.

  3. In VS Code, use command palette Simple Browser Multi: Show and enter the url in Step 2 to open the preview in the internal browser.

In VS Code

By default Quarto does NOT automatically render .qmd or .ipynb files when you save them. This is because rendering might be very time consuming (e.g. it could include long running computations) and it’s good to have the option to save periodically without doing a full render.

You have to refresh to see your updates when using VS Code command palette quarto preview.

You can render a Quarto document in VS Code using the command palette:

  • Quarto: Render Document to render the document.
  • Quarto: Render Project to render the entire project.
  • Quarto: Preview to preview the default document in a web browser. If you want to preview a different format, use the Quarto: Preview Format command:

This will show a preview of the project in the internal browser.

However, you can configure the Quarto extension to automatically render whenever you save. In settings, set quarto.renderOnSave to true.

You might also want to control this behavior on a per-document or per-project basis. If you include the editor: render-on-save option in your document or project YAML it will supersede whatever your VS Code setting is. This works on a per-document basis. For example:

---
editor:
  render-on-save: true
---

Alternatively, you can set it globally in VS Code settings:

"quarto.render.renderOnSave": true

After you enable render-on-save, when you save your qmd file, the preview will be updated in time. It is suggested to configure how often the file is saved in VS Code settings:

"files.autoSave": "onFocusChange"

The file will be saved when focus changes.

Options for files.autoSave:

Value Behavior
"off" Never auto-saves (manual Cmd+S only)
"onFocusChange" Saves when you click away from the editor
"onWindowChange" Saves when you switch away from the VS Code window
"afterDelay" Saves after a set delay (e.g. 1000ms)

ref: Quarto: Render on Save

Q: Quarto Preview pane not refreshing and updating changes.
A: The issue seems to come from the --no-watch-inputs option to the preview command, preventing the live update. ↩︎

Use the following command in terminal to enable live preview:

quarto preview "path-to-file/file-name.qmd"

Copy and paste the url to the internal browser in VS Code. The command supports live preview. When you make changes to your qmd file and save, the preview will be updated in time.

In R

quarto::quarto_render(input = NULL, output_format = "html") can be used to render a Quarto document or project in R.

  • If input is not specified, it will render the current Quarto project. If input is specified, it will render the specified Quarto document.

  • If output_format is not specified, it will render the document to HTML. You can specify other formats such as PDF or Word.

    • output_format = "all" will render all formats specified in the _quarto.yml file.
# Render a Quarto document to HTML
quarto::quarto_render("0304-Quarto.Rmd", output_format = "html")
# Render a Quarto project to HTML
quarto::quarto_render(output_format = "html")
# Render a Quarto document to PDF
quarto::quarto_render("0304-Quarto.Rmd", output_format = "pdf")
# Render a Quarto project to PDF
quarto::quarto_render(output_format = "pdf")

Alternatively, you can use the Render button in RStudio. The Render button will render the first format listed in the document YAML. If no format is specified, then it will render to HTML.