bug-reports.qmd

---
title: "Bug Reports"
subtitle: "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: 

```bash
export QUARTO_PRINT_STACK=true
quarto render document.qmd
```

or on Windows in a Powershell Terminal

```powershell
$ENV:QUARTO_PRINT_STACK="true"
quarto render document.qmd
```