quarto-dev / quarto-dev/quarto-cli

Document in more places that `output-dir` will be deleted

Open
#13,896 7 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

The output directory is (usually) completely deleted (see eg #13623). In the related issue #13892, @mcanouil said

See quarto render --help .

However, quarto render --help does not actually say anything about this rather important point. Currently, this is what it says:

  --output-dir                        - Write output to DIR (path is input/project relative)

and I propose changing this to, perhaps:

  --output-dir                        - Write output to DIR, which is first deleted if it exists (path is input/project relative)

This misses some subtlety, of course.

I'm currently trying to find where in the docs it actually says that the directory will be deleted. I'm sure it says it somewhere, but it's a bit hard to find. I would suggest adding this VERY IMPORTANT caveat to all the places it discusses output-dir.

For instance, on project options:
Image

Same thing on project options for websites:
Image

Similarly, this fact is not mentioned on the Output Path section for books.

Tangentially, this is not mentioned either in at least this place in TPG.

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 with quarto render --help and the linked project options, website project options, book output path, and TPG project options pages to locate every output-dir description. Update the relevant documentation and help text so the deletion caveat is stated wherever output-dir is discussed, then verify the rendered pages and help output.

Written by the indexing model from the issue text.

Assessment

Domain
cli, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.