Bug Reports

How to make an actionable bug report for Quarto

We want to hear about Quarto bugs and, we want to fix those bugs! The following guidance will help us be as efficient as we can.

Rule 0: Please submit your bug report anyway!

We have a better chance to fix your code quickly if you follow the instructions below. Still, we know that this takes work and isn’t always possible.

We would rather have a record of the problem than not know about it.

We appreciate bug reports even if you are unable to take any or all of the following steps:

Small is beautiful: Aim for a single document with ~10 lines

The most helpful thing you can do to help us is to provide a minimal, self-contained, and reproducible example.

  • minimal: This will often mean turning your large website project into a project with a single small document, and a single large .qmd file into a small (ideally, about 10-20 total lines of code) example. By doing this, you might also be able to learn more specifically what the problem is.
  • self-contained: The more software dependencies we need to understand and install, the harder it is to track the bug down. As you reduce the code, remove as many dependencies as possible.
  • reproducible: If we cannot run your example, we cannot track the bug down. Please make sure the file you submitted is enough to trigger the bug on its own.

Formatting: Make GitHub’s markdown work for us

You can share a minimal self-contained reproducible Quarto document using the following markdown syntax, i.e., using more backticks than you have in your document (usually four ````) to account for code cells.

````qmd
---
title: "Reproducible Quarto Document"
format: html
engine: jupyter
---

This is a minimal self-contained reproducible Quarto document using `format: html` and `jupyter` engine.
It is written in Markdown and contains embedded Python code.

```{python}
print("Hello, world!")
```

![An image]({{< placeholder 600 400 >}}){#fig-placeholder}

{{< lipsum 1 >}}

A reference to @fig-placeholder.

The end.
````
````qmd
---
title: "Reproducible Quarto Document"
format: html
engine: knitr
---

This is a minimal self-contained reproducible Quarto document using `format: html` and `knitr` engine.
It is written in Markdown and contains embedded R code.

```{r}
print("Hello, world!")
```

![An image]({{< placeholder 600 400 >}}){#fig-placeholder}

{{< lipsum 1 >}}

A reference to @fig-placeholder.

The end.
````

Don’t hold back: Tell us anything you think might make a difference

Although we want the .qmd file to be small, we still can use as much information from you as you’re willing to share. Tell us all!, including:

  • The version of Quarto you’re running
  • The operating system you’re running
  • The IDE you’re using, and its version

Check

You can provide the output (within a code block) of the following command to help us understand your environment:

quarto check

For instance, the markdown code you would provide might look like this:

```bash
Quarto 1.5.42
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.2.0: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.41.0: OK
      Typst version 0.11.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.5.42
      Path: /Applications/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: v2024.03.13
      Chromium: (not installed)

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /Users/username/Library/TinyTeX/bin/universal-darwin
      Version: 2024

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.12.1
      Path: /.venv/bin/python3
      Jupyter: 5.7.2
      Kernels: julia-1.10, python3

[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........OK
      Version: 4.3.3
      Path: /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources
      LibPaths:
        - /Users/username/Library/R/arm64/4.3/library
        - /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/library
      knitr: 1.45
      rmarkdown: 2.26

[✓] Checking Knitr engine render......OK
```