bug-reports.qmd

---
title: "Bug Reports"
subtitle: "How to make an actionable bug report for Quarto"
toc-depth: 3
---

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 {#formatting-make-githubs-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.

::: {layout-ncol="2"}

`````{.md shortcodes=false}
````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.
````
`````

`````{.md shortcodes=false}
````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:

```bash
quarto check
```

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

````md
```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
```
````

### Print stack

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
```