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
The easiest way to include a .qmd
file in a comment is to wrap it in a code block. To make sure that GitHub doesn’t format your own .qmd
, start and end your block with more backticks than you use in your .qmd
file. In order to show .qmd
files with three backticks (the most common case), use four backticks in your GitHub Issue:
```
This is a code block
```
Sometimes you might need more backticks:
````
This is a four backticks block.
```
This is a code block
```
````
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
If you are seeing an error from Quarto, you can also provide additional diagnostic information by defining the QUARTO_PRINT_STACK
environment variable.
For example on Unix:
export QUARTO_PRINT_STACK=true
quarto render document.qmd
or on Windows in a Powershell Terminal
$ENV:QUARTO_PRINT_STACK="true"
.qmd quarto render document