quarto-dev / quarto-dev/quarto-cli

Feature request: Document writing to logfile + surface logfile info in a user-friendly way in various editors

Open
#7,154 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

When working on, particularly, a large project, there is sometimes important information in the Quarto log that is easy to miss when rendering. For example, if rendering in RStudio with "Render Book", this information is printed in the Background Jobs pane, but it scrolls away quickly, and it's not trivial to find it in there, and definitely not easy to remember to do so.

It is possible to write to a logfile with

quarto render --log my-log-file.txt

In the short term, it would be good to:

  1. Document this, perhaps at https://quarto.org/docs/troubleshooting?
  2. Make it possible to request a log file via the project or document yaml, so one doesn't need to render with the CLI to get it.
  3. If possible, make what gets captured in the log file consistent between output formats. For example, if you have a Quarto book with an image embedded but the image file is missing, this doesn't get captured in the logfile when rendering to HTML (it's instead printed in the Background Jobs pane while previewing the book) but it is captured as an ERROR if rendering to PDF.

In the longer term (1.5?), it would be nice if editors like RStudio, VSCode, etc. could parse and surface this information in a warnings or similar pane.

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 the existing quarto render --log my-log-file.txt behavior and the troubleshooting documentation. Then trace how project or document YAML could request a logfile and compare what is captured for HTML and PDF rendering, including missing images. Done means the requested logging behavior is documented and the captured information is consistent enough for the stated use cases.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.