`--output-dir` fails in a project that sets `project.output-dir`

Open Beginner friendly
#1,133 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
82/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
rust
Domain
build-system

Research direction

Start in crates/quarto-core/src/render_to_file.rs, where --output-dir is applied to page output and the resource resolver is configured; compare the HTML path with the handling for docx and typst. Check crates/quarto-core/src/resource_resolver.rs for the allowed-root check. Done when rendering with --output-dir out writes the page and support files under out, leaves _site alone, and reports out in the summary.

Written by the indexing model from the issue text.

Description

Bug description

To compare q2 with Quarto 1 on the dashboard from #1131, I wanted the q2 output in its own folder, away from the _site/ that Quarto 1 publishes.
The project sets output-dir: _site, and q2 render index.qmd --output-dir out stops on the first support file.
The relative and the absolute form of the path give the same error.

The page itself follows the option: when --output-dir is given, the project output-dir is skipped:

https://github.com/quarto-dev/q2/blob/8f17e950d26c68daae6e794c5fa513a96c0dae68/crates/quarto-core/src/render_to_file.rs#L763-L784

The writes, though, go through a resource resolver whose site_root is still the project output-dir, and that root is the only place the output sink accepts.
A comment in the same file describes this stock resolver and moves site_root for docx, typst and similar formats, but HTML keeps it:

https://github.com/quarto-dev/q2/blob/8f17e950d26c68daae6e794c5fa513a96c0dae68/crates/quarto-core/src/render_to_file.rs#L695-L716

https://github.com/quarto-dev/q2/blob/8f17e950d26c68daae6e794c5fa513a96c0dae68/crates/quarto-core/src/resource_resolver.rs#L318-L323

Steps to reproduce

_quarto.yml:

project:
  type: default
  output-dir: _site

index.qmd:

---
title: Hello
---

Hello.
q2 render index.qmd --output-dir out
quarto render index.qmd --output-dir out
Actual behavior

q2 writes nothing:

Rendering project: <dir> (type: default)
error: <dir>/index.qmd: output destination <dir>/out/index_files/quarto/quarto-theme-d9a3a2debf57bcb1.css is not under any allowed root (<dir>/_site)
Rendered 0 of 1 files to <dir>/_site — 1 error

The summary line names _site, not out.
Quarto 1 writes out/index.html and out/index_files/, and leaves _site/ alone.

Expected behavior

out/ gets the page and its support files, as with Quarto 1, and the summary names out.
Building the resolver with site_root set to the --output-dir value whenever the option is given would cover it.

Your environment
  • q2: q2 (quarto 2) 0.43.0-nightly.20261109 (nightly built from 8f17e95), and q2 v0.42.0.
  • Quarto 1 for comparison: development build of quarto-dev/quarto-cli@fa74261.
  • OS: macOS 27.2 (arm64).
  • Terminal, no IDE.
Dominant language
Rust
Stars
302
Forks
22
Avg merge
5h 2m
Merged PRs (30d)
213

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from quarto-dev/q2

All issues in quarto-dev/q2

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.