How to include format-links in html of the book project?

[TomBener]

Description

With the command quarto create project book mybook, I created a demo book project. But by running quarto render --to html, the generated html does not include other formats (docx, pdf), even if the format-links: true was added in _quarto.yml. Also, I found that by running quarto render --to html, the prior outputs under _book would be removed. Is this a bug or feature?

What I want to achieve in the book project:

1. Include other format links in html with format-links: true.
2. Include multiple kinds of file formats in the generated folder (_book by default) at the same time.

I use Quarto 1.5.9 on macOS 14.4.1:

$ quarto check

Quarto 1.5.29
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.11: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.41.0: OK
      Typst version 0.11.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.5.29
      Path: /Applications/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: v2024.04
      Chromium: (not installed)

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /Users/username/Library/TinyTeX/bin/universal-darwin
      Version: 2024

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.10.10
      Path: /Users/username/.pyenv/versions/3.10.10/bin/python3
      Jupyter: 5.5.0
      Kernels: python3

[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........OK
      Version: 4.3.3
      Path: /opt/homebrew/Cellar/r/4.3.3/lib/R
      LibPaths:
        - /Users/username/.R/packages
        - /opt/homebrew/lib/R/4.3/site-library
        - /opt/homebrew/Cellar/r/4.3.3/lib/R/library
      knitr: 1.45
      rmarkdown: 2.25

[✓] Checking Knitr engine render......OK

[mcanouil]

For format-links to work, you need to render all formats involved.
Why do you specify --to html?

Also, I found that by running quarto render --to html, the prior outputs under _book would be removed. Is this a bug or feature?

You should not have anything under _book that is not defined in your book.
Use resources to list external resources and ensure they are copied to the output location, see https://quarto.org/docs/websites/website-tools.html#site-resources.

[TomBener]

Thanks. But by executing quarto render to render all format still didn't include format-links in html. The _quarto.yml:

project:
  type: book

book:
  title: "My Book"
  author: "Norah Jones"
  date: "4/12/2024"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

bibliography: references.bib

format:
  html:
    theme: cosmo
    format-links: true
  pdf:
    documentclass: scrreprt

[mcanouil]

Oh, so format-links is actually not valid in Book project.
I believe, it's because you have:

book:
  downloads: [pdf]

For this purpose, which is described in https://quarto.org/docs/books/book-output.html#sidebar-tools.

[TomBener]

Great! This approach works. But in my use-case, I want to render outputs with some tweaks, so I use Makefile to build them. Here is a snippet:

# Quarto command
QUARTO_CMD := @quarto render --to

# AutoCorrect command
AUTOCORRECT := @cd _thesis && autocorrect --config ../.autocorrectrc --fix

# Target rules for rendering output formats
docx epub pdf: $(QMD_FILES)
	@python formd.py
	$(QUARTO_CMD) $@ $(if $(findstring pdf,$@),--output $(PDF_OUTPUT) $(PDF_OPTION) -M bibliography=$(BIB_FILE),)

# Sort Chinese bibliographies based on Pinyin
# Add spacing between Chinese and English words in HTML
html: $(QMD_FILES)
	$(QUARTO_CMD) $@
	@python pinyin-sort-html.py
	$(AUTOCORRECT) *.html

In the code, PDF output uses .bib file, while other formats uses .json file for bibliography, and extra text formatting is also applied. As a result, it is not a good idea to use quarto render to build all formats at the same time. However, if I use make html, and then make pdf, the prior outputs will be removed, so the downloads: [pdf] becomes meaningless. How can I avoid the issue?

[mcanouil]

Add a step in your custom builder/renderer to move the files around for instance using --output-dir to change the location of the output on the fly.

I'm afraid, Quarto cannot support all custom things like that.

[TomBener]

Good idea. Thanks!

[TomBener]

But is it possible that Quarto does not remove prior outputs in the output directory 😬