Workflow issues building both HTML and PDF of a Quarto book

[friendly]

Description

[
ENV: R 4.5.1 / RStudio 2025-05.0-496 / Quarto: 1.7.29
if useful, here is my _quarto.yml
]

When I started writing my book, I chose to use Quarto over bookdown because I thought it would be easier to produce both the printed PDF and online HTML versions from the same source (using conditikonal divs like .content-visible when-format=)

I mostly worked with the HTML version, but now that it's nearly done, I am more frequently compiling both versions, and run into the following problems

• when I use Build -> Render book -> PDF format, all the docs/*.html files are deleted
  along with the .png images under docs/ (I'm using friendly.github.io to host the online version.). So,, I have to render it again in HTML.

$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   bib/pkgs.txt
        deleted:    docs/00-Author.html
        deleted:    docs/00-Prelude.html
        deleted:    docs/01-intro.html
        deleted:    docs/02-getting_started.html
        deleted:    docs/03-multivariate_plots.html
        deleted:    docs/04-pca-biplot.html

  ...

• if I use Build -> Render book -> All formats, all of the cross-references in the HTML version appear incorrectly as Figure fig-tag rather than Figure 2.1. Same for chapter/section xrefs, as shown below.

Consequently, when I'm done with an editing pass, I have to do separate runs of both All formats followed by HTML format before I git push. This is a pain, b/c it takes ~ 15 min for a single pass.

Unless I've missed something, I think this might count as a bug in Quarto rendering.

[mcanouil]

Did you try doing quarto render from the command line?

(I just worked on a book for a client and did not have the issue, but I don't use UI)

edit: you might want to cleanup your _quarto.yml, there are missplaced (commented) options, options set at different levels (your parse-latex filter is set at two different levels), etc.

[friendly]

That may be a useful tip. because I mainly use the UI. What would the terminal command be to render PDF and HTML in one pass, without getting the problems I encounter?

My most recent pass (b/c I was trying to demonstrate the behaviour) to re-build the HTML that had been F%%D up, used this command in the Background Jobs window

quarto preview --render html --no-watch-inputs --no-browse

[mcanouil]

The command I showed will render all formats defined in project.

You can also do it explicitly: quarto render --to all

You can view the help of the Quarto commands with --help: quarto render --help.

[cscheid]

Unless I've missed something, I think this might count as a bug in Quarto rendering.

I'm sorry that you're running into this. It's definitely a bug somewhere which someone at Posit should address. As @mcanouil mentioned, we need to sort out what RStudio does with those options. Let me do a bit of internal investigation and get back to you.

[cscheid]

In my RStudio options, I don't see a "Build -> Render book -> All formats" path with a newly-created quarto book. I either see "Render Book" on the main menu, or "Render -> Render {HTML, PDF}" on the "Render" button on the page.

@friendly Where are you seeing this UI?

[friendly]

Here's what I see in my slightly different RStudio versions on several machines:

That's because my _quarto.yml specifies both format: s

The Background Jobs tab shows this as the command:

quarto preview --render all --no-watch-inputs --no-browse

Interestingly, when I just tried this, the very first thing that happened, is that all my docs/*.html and docs/figs/*.png files were deleted, so to recover my previous state, I had to do git stash

[cscheid]

Thank you, that's helpful. I'll get back to you.

[cderv]

the very first thing that happened, is that all my docs/.html and docs/figs/.png files were deleted

@friendly when you do call quarto render it will first delete the output directory, which in your case is docs (https://github.com/friendly/Vis-MLM-book/blob/8251e67ff569caf361f1ab4c3f0b114ef31275c3/_quarto.yml#L3)

This is done to get a clean state to re-render everything. But quarto render should render both your PDF and your HTML and it definitely shouldn't have the cross-references in the HTML version appearing incorrectly.

I am curious if this is a problem in the UI and if a call to quarto render inside your terminal leads to correct outputs.

This is a pain, b/c it takes ~ 15 min for a single pass

Several hints to ease your workflow:

• Incremental Rendering is here so that you don't have to render the whole book each time when you work on a part of it

• Regarding execution time, the freeze feature is here so that rendering the whole book is much faster than re-running the book including all execution each time.
  This is useful has, as you notice, quarto render is designed currently to deleted output-dir and re-render the whole book in all format versions

• Quarto profile could be a way to have one output-dir per format, which means you could do quarto render --to pdf without having your HTML version remove. It could be something like quarto render --profile html & quarto render --profile pdf where _quarto-html.yml would have a specific output-dir and defines format: html, and _quarto-pdf.yml would have another output-dir and format: pdf configuration.

Those may seems advanced, but they can probably help in your workflow at some point.

Hope it helps.

We'll see with RStudio folks to improve the experience in the UI, and make that clear.

[friendly]

Thx @mcanouil and @cderv for these helpful comments.

I just tried from the terminal quarto render --to all and the results were quite different than before.

• With my _quarto.yml configuration, all the TeX related files (index.tex, index.log, index.aux, ...) were written to the top-level root directory, but the PDF image files from code chunks were written to docs/figs/Ch01, docs/figs/Ch02, ...
• Now, all the PDF image files are written to top-level figs/Ch01, figs/Ch02, ... folders.
• This is somewhat untidy, but it works, in the sense that I can produce the final PDF from ./index.tex using TeXStudio -- it finds all the image files as before.

Yet, in this, the problem of xrefs in the HTML version remains the same --they all appear as sec-tag rather than Section 2.1

Thus, this approach is of no use to me -- I still have to re-render to HTML to get the web version correct. I think this should be classified as a bug.

What I have in my _quarto.yml may help to understand what's happening here. At the top, I define the project: to use output-dirL docs so that the HTML will be written there for GitHub to publish

project:
  type: book
  output-dir: docs

book:
  title: "Visualizing Multivariate Data and Models in R"
  subtitle: "A Romance in Many Dimensions"
  # output-file: "Vis-MLM"
  author:
    - name: Michael Friendly

Note that I had tried using output-file: Vis-MLM, but this gave weird results when I tried to compile the PDF.

I also defined the fig.path: figs/ under a knitr: section in the .yml,

knitr:
  opts_chunk:
    fig.path: figs/

But, then each in each chapter.qmd file this was re-defined to use a separate folder for that chapter.

```{r include=FALSE}
source("R/common.R")
knitr::opts_chunk$set(fig.path = "figs/ch02/")
```

Incremental rendering

This works very well for the HTML version: The current chapter is rendered, and the preview I see in the browser at localhost: or from file:// looks OK. I have other unresolved issues regarding LaTeX, #13479 so I can't easily test incremental rendering for the PDF.

I'll look into freeze https://quarto.org/docs/projects/code-execution.html#freeze

I've looked at the info on Quarto profiles, but I don't see how to adopt it for my simple (??) situation of wanting to get both HTML & PDF without tears.

[mcanouil]

Is it on purpose you have references to a document you commented in your _quarto.yml? (sec-discoveries)

I would also suggest you set up renv in your project and record version for easier reuse by others.

I had to do the following, then remove/reinstall patchwork because for some reason something in _dependencies.R install a different patchork from the r-forge.

renv::init(bare = TRUE)
# restart
renv::install(c("rmarkdown", "dply", "pak"))
source("_dependencies.R")
# wait
renv::snapshot()

Possibly using "explicit" mode via a DESCRIPTION where you list explicitly what your project needs to record.

[friendly]

In the .qmd text of chapters there are two references to @sec-discoveries. I know these don't resolve, because that chapter is currently .unnumbered. I plan to fix that, but with my file naming scheme, I should rename the chapter files from there to the end.

renv was too much of a pain while I was writing, but maybe I can set this up for the future. The _dependencies.R file was setup by my RA.

[mcanouil]

renv was too much of a pain while I was writing,

Thus the explicit mode to avoid detection which quite slow down R in big projects.
You list all packages in DESCRIPTION:

Imports:
  ggplot2,
  dplyr,
  ...

This saves times, It took me quite some time to get your book working and I'm pretty sure I'm not even running the same R packages versions you are thus differences can be expected.

[mcanouil]

If I may, I would also suggest to harmonise one way or another how you set knitr and Quarto options, you using:

• YAML syntax in _quarto.yml.
• Using R script to set knitr options (source()) which you set again via R code in the same code cell.
• Using R inline and at the same time YAML syntax for code cells, you have to choose.

```{r}
#| label: my-label
#| include: false
#| fig-path: path/to/fig/
```

(recommended in Quarto)

but not:

```{r my-label, include = FALSE}
#| fig-path: path/to/fig/
```

This makes it harder to track what changes and where.

[mcanouil]

After all this, I'm unable to reproduce a cross-reference issue.
After changing the krantz.cls file to ensure the PDF can render (see #13479 (comment)), doing quarto render --to all lead to a proper HTML version:

[friendly]

SUCCESS!
Fixing the problem with krantz.cls mentioned in #13479 also makes this issue go away.

For the record: I get both PDF and HTML versions with the UI menu Build -> Render Book -> All formats. The difference from before are:

• The .tex file is named ./Visualizing-Multivariate-Data-and-Models-in-R.tex (not index.tex as before)
• The generated PDF file is named Visualizing-Multivariate-Data-and-Models-in-R.pdf and placed under docs/, along with all the .html files.

This is despite the fact that my _quarto.yml includes output-file: Viz-MLM

  pdf:
    documentclass: krantz
    classoption: [10pt, krantz2, titlepage, letterpaper]
    include-in-header: latex/preamble.tex
    include-before-body: latex/before-body.tex
    include-after-body: latex/after-body.tex
    # latex-output-dir: pdf
    output-file: Vis-MLM

I owe you guys several rounds of drinks next if we ever meet in person, but I also acknowledge your help in the Preface.