Skip to content

{{< include >}} shortcode leads to unhelpful stacktraces #13400

@jkrumbiegel

Description

@jkrumbiegel

I have:

  • searched the issue tracker for similar issues
  • installed the latest version of Quarto CLI
  • formatted my issue following the Bug Reports guide

Bug description

When a qmd includes another one via the {{< include >}} shortcode and code in the included document errors, the stack trace points to the line in the final concatenated document where the executed code ended up. For example, A.qmd includes B.qmd at line 101 and the erroring code is in line 200 in B.qmd. The stacktrace will point to A.qmd line 300. This is not helpful for users because they cannot easily find the place where the erroring code actually was.

Steps to reproduce

Any qmd which uses {{< include some_other.qmd >}} will show this behavior.

Actual behavior

No response

Expected behavior

It would be better if quarto tracked the location of included code and corrected the stack traces with that information. I know that the MappedString type already supports this functionality, and options.target.markdown is of this type (this is the string that gets sent over to Julia).

I have tried to hotfix this behavior on the julia engine side but it turned out that the way quarto includes documents causes strange newlines and I generally don't want to replicate quarto's machinery, so I dropped that attempt PumasAI/QuartoNotebookRunner.jl#338.

I have a draft PR #13401 that implements a basic quarto-side solution to this, but I wanted to get maintainer feedback first how you want to handle this situation in general. I've checked the knitr and python engines and they also don't use included files in stack traces but just reference the main file. I couldn't find a preexisting issue but I might've missed it.

My code outputs info like this for a basic file with nested includes, you can see that there are empty lines in there with no attached source files, I think that's a bug on quarto's side. Although practically it wouldn't matter, as empty lines cannot cause stack traces that need to point to them.

[
  {
    lines: [ 1, 5 ],
    file: "scratch/scratch.qmd",
    sourcelines: [ 1, 5 ]
  },
  {
    lines: [ 6, 9 ],
    file: "/Users/krumbiegel/dev/quarto-cli/scratch/_inner_include.qmd",
    sourcelines: [ 1, 4 ]
  },
  { lines: [ 10, 10 ] },
  {
    lines: [ 11, 17 ],
    file: "/Users/krumbiegel/dev/quarto-cli/scratch/subfolder/_include.qmd",
    sourcelines: [ 1, 7 ]
  },
  { lines: [ 18, 18 ] },
  {
    lines: [ 19, 25 ],
    file: "scratch/scratch.qmd",
    sourcelines: [ 7, 13 ]
  },
  {
    lines: [ 26, 26 ],
    file: "scratch/scratch.qmd",
    sourcelines: [ 13, 13 ]
  }
]

Your environment

No response

Quarto check output

% quarto check
Quarto 99.9.9
[✓] Checking environment information...
      Quarto cache location: /Users/krumbiegel/Library/Caches/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.6.3: OK
      Dart Sass version 1.87.0: OK
      Deno version 2.3.1: OK
      Typst version 0.13.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 99.9.9
      commit: 887a22098b07722c1a0b58577b478a5c95b523d0
      Path: /Users/krumbiegel/dev/quarto-cli/package/dist/bin

[✓] Checking tools....................OK
      TinyTeX: v2025.01
      Chromium: (not installed)

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

[✓] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
      Source: MacOS known location

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

[✓] Checking Python 3 installation....OK
      Version: 3.12.2 (Conda)
      Path: /Users/krumbiegel/miniconda3/bin/python
      Jupyter: 5.5.0
      Kernels: julia-1.11, julia-1.10, julia-1.8, julia-1.7, python3

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

[✓] Checking R installation...........OK
      Version: 4.5.1
      Path: /Library/Frameworks/R.framework/Resources
      LibPaths:
        - /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/library
      knitr: 1.50
      rmarkdown: 2.29

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

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingincludesqmd-syntaxIssues related to the syntax of qmd documents.

Type

No type

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions