quarto-dev / quarto-dev/quarto-cli

Better handling of `--output` when multiple formats

Open
#8,399 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement files
Dominant language
JavaScript
Stars
6k
Forks
458
Avg merge
1d 9h
Merged PRs (30d)
41

Description

Initially reported at https://github.com/quarto-dev/quarto-r/issues/43. Mostly because we do provide output_file argument in R quarto_render() function, which is passed to --output flag.

---
title: "Example title"
format:
  html: default
  docx: default
---

This is a simple example file. 

Currently providing --output does provide any check or guidance on what it will results. And running quarto render index.qmd --output final_report will

  • Render two formats
  • create a final_report file without extension

From quarto-dev/quarto-r#43, OP expects extensions to be added when a single --output with no extension is passed so final_report.html and final_report.docx is created.

This could be a valid scenario. But even if we don't go by this one, there should probably be warning about what quarto will do (because there will be overwrite and unusable output), or even error as a single --output will lead no matter what to a single output for multiple format.

All the more, because this leads to broken file created without any error or warning.

> quarto render index.qmd --output final_report.html
pandoc --output final_report.html
  to: html
  standalone: true
  section-divs: true
  html-math-method: mathjax
  wrap: none
  default-image-extension: png

metadata
  document-css: false
  link-citations: true
  date-format: long
  lang: en
  title: Example title

pandoc --output final_report.html
  to: docx
  default-image-extension: png

metadata
  title: Example title

Output created: final_report.html

--output is really expected to be a filename and can't be used when --to is not a single format really.

We should either improve the situation by allow multiple output, this "auto extension feature", or just disallow the usage;

IMO better user experience is what we should aim on this

Contributor guide

Open the contributing guide

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.

Research direction

Start by reproducing quarto render index.qmd --output final_report with the two formats shown, then trace the CLI's --output handling. Done should prevent silently overwriting or producing an unusable extensionless file, either by supporting distinct outputs or clearly rejecting or warning about this combination.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, r
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.