Quarto preview and use of output-dir flag

[bensoltoff]

System details

Positron Version: 2025.09.0 build 139
Code - OSS Version: 1.103.0
Commit: 30e3d0a
Date: 2025-08-29T18:31:36.739Z
Electron: 37.2.3
Chromium: 138.0.7204.100
Node.js: 22.17.0
V8: 13.8.500258-electron.0
OS: Darwin arm64 24.6.0

R 4.5.1
Quarto 1.8.24

Issue rendering and previewing Quarto documents

I've been having sporadic issues rendering and previewing Quarto documents in Positron (see #9158), but haven't been able to generate an isolated reproducible example. From what I have been able to evaluate, it seems related to Positron using the output-dir flag in the Terminal command.

If I render a Quarto document in RStudio, it executes the Terminal command

quarto preview test-doc.qmd --to html --no-watch-inputs --no-browse

and opens the previewed document in my browser.

In Positron, when I click the Preview button it typically runs a command like

quarto preview /Users/bcs88/Projects/info-5001/assessments/test-doc.qmd --no-browser --no-watch-inputs --ou
tput-dir /var/folders/y5/0kt9x9qd2f13mtkqx3w0lh9r0000gr/T/tmp-58424-5O1k9emicUXN --embed-resources

It often fails one of two ways. Occasionally the document is successfully rendered, but then the preview cannot be opened with an error like

Output created: ../../../../../../var/folders/y5/0kt9x9qd2f13mtkqx3w0lh9r0000gr/T/tmp-58424-5O1k9emicUXN/exam/quiz-01-I.html

Watching files for changes
Browse at http://localhost:3329/../../../../../../var/folders/y5/0kt9x9qd2f13mtkqx3w0lh9r0000gr/T/tmp-58424-5O1k9emicUXN/test-doc.html
Listening on http://127.0.0.1:3329/
GET: /var/folders/y5/0kt9x9qd2f13mtkqx3w0lh9r0000gr/T/tmp-58424-5O1k9emicUXN/test-doc.html (404: Not Found)

More often, it doesn't even render the document with the error

bcs88@COECIS-HJGTG2FW6P assessments % quarto preview /Users/bcs88/Projects/info-5001/assessments/test-doc.qmd --no-browser --no-watch-inputs --ou
tput-dir /var/folders/y5/0kt9x9qd2f13mtkqx3w0lh9r0000gr/T/tmp-11660-6pp5ran01wyN --embed-resources
ERROR: NotFound: No such file or directory (os error 2): stat '/Users/bcs88/Projects/info-5001/assessments/.quarto/quarto-session-temp3b2c61181a26aef0'

Stack trace:
    at Object.statSync (ext:deno_fs/30_fs.js:415:3)
    at createWalkEntrySync (file:///Applications/quarto/bin/quarto.js:2163:22)
    at walkSync (file:///Applications/quarto/bin/quarto.js:2283:11)
    at walkSync.next (<anonymous>)
    at advanceMatch (file:///Applications/quarto/bin/quarto.js:2401:21)
    at advanceMatch.next (<anonymous>)
    at expandGlobSync (file:///Applications/quarto/bin/quarto.js:2423:18)
    at expandGlobSync.next (<anonymous>)
    at expandGlobs (file:///Applications/quarto/bin/quarto.js:6095:18)
    at resolveGlobs (file:///Applications/quarto/bin/quarto.js:6178:24)

I have tried manually clearing the .quarto cache folder by deleting it entirely. When this error appears, I can see a quarto-session-temp folder generated, but it has a different hash value.

Does anyone know why Positron uses the output-dir flag when previewing Quarto documents?

[bensoltoff]

As a workaround I've been using the command palette to "Quarto: Render document" directly and skip the preview step. Recently that has also produced the same error ERROR: NotFound: No such file or directory (os error 2): stat '/Users/bcs88/Projects/info-5001/assessments/.quarto/quarto-session-temp3b2c61181a26aef0'.

As I was writing the post, I noticed that it's a two step process. After selecting "Quarto: Render document", I have to select which file format I want to generate. Normally I generate all specified formats in the YAML header. Because I do it so often, I just do a double-tap on the return key. I had Finder open on my desktop and I could see the quarto-session-temp folder being generated. If I selected the file format option too quickly, it looked like that is when the error occurred. If I waited a second to select the file format, I saw the quarto-session-temp folder generated before the shell command was executed in Positron. Is it simply a matter of waiting for the temp folder to be generated before quarto render actually processes the document?

If so, could that explain the issue with quarto preview? Is it getting ahead of the folder creation?

[juliasilge]

I worked a bit on some of this behavior, for example in quarto-dev/quarto#435. My current understanding is that Quarto will render with --embed-resources and with a temporary --output-dir when the workspace is an R package, and will not do so if the workspace is not an R package. We have this behavior so R package developers can preview vignettes and READMEs and such inside of an R package. Positron doesn't have any capability to render or preview .Rmd or .md outside of using Quarto.

Is this a "real" R package that you really want to treat as such? For example, would it be a pretty big problem for you if the output HTML output for a, say, vignette gets added to your workspace? If you are using the R package infrastructure to manage your project, but you don't want Quarto to think it's an R package, you could do something like add Type: Analysis or Type: Book or similar to your DESCRIPTION file, to signal that this isn't a traditional R package. Check out the R package detection in Quarto here:
https://github.com/quarto-dev/quarto/blob/4d2f2cc1a25ab5471a36f0a304bef3b5b6eacf09/apps/vscode/src/providers/preview/preview-util.ts#L63

In terms of the problems you are seeing, I just played around for quite a while and I can't seem to generate the same error but it sounds like you have done some good detective work to maybe identify a race condition. Can you describe the problem you are using in a post at https://github.com/quarto-dev/quarto-cli/discussions? I believe this may be something the Quarto team needs to work on, to wait until a folder gets created before trying to write to it.

[bensoltoff]

It's not a real package. I use the DESCRIPTION file to list some dependencies for {renv} which explains why it thinks the repo is a package. I'll test your suggestion to modify the DESCRIPTION file and see if that changes anything.

[juliasilge]

If you put Type: Analysis or similar, it will make the rendering more like:

quarto preview test-doc.qmd --to html --no-watch-inputs --no-browse

However, I don't think it will fix problems of the nature you described in #9472 (comment); I think that will need to get fixed by the Quarto CLI itself.