[Book] Cross reference doesn't work if `output-file` is used

[iagobaapellaniz]

I have:

• searched the issue tracker for similar issues
• installed the latest version of Quarto CLI
• formatted my issue following the Bug Reports guide

Bug description

Cross reference is unable to find any reference of content of a page/chapter which's output filename has been changed by the user.

Index file

---
output-file: index-es
---

# Chapter 1

This is an example.

## Section 1.1 {#sec-test}

Awesome section.

Test file

# Chapter 2

I would like to ref. @sec-test

I think that if the bug is not fixable, we can update the documentation warning the user for this constraint.
I think that this issue mainly can happen only in book projects.

Steps to reproduce

No response

Actual behavior

No response

Expected behavior

No response

Your environment

No response

Quarto check output

quarto check

[✓] Checking environment information...
      Quarto cache location: /Users/iagoba/Library/Caches/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.6.3: OK
      Dart Sass version 1.85.1: OK
      Deno version 1.46.3: OK
      Typst version 0.13.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.7.32
      Path: /Applications/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: v2025.03.10
      Chromium: (not installed)

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

[✓] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
      Source: MacOS known location

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

[✓] Checking Python 3 installation....OK
      Version: 3.13.2
      Path: /opt/homebrew/opt/python@3.13/bin/python3.13
      Jupyter: (None)

      Jupyter is not available in this Python installation.
      Install with python3 -m pip install jupyter

[✓] Checking R installation...........(None)

      Unable to locate an installed version of R.
      Install R from https://cloud.r-project.org/

[mcanouil]

Why do you want to set output-file in a chapter?
Most books formats are single file and take their options from the project file _quarto.yml.
Only the HTML version is kind of in between a single file and a website.
Even in that case, what do you expect to happen here?

I don't believe the documentation mention to use this option like that in books.
See https://quarto.org/docs/books/book-output.html#output-path.

[iagobaapellaniz]

I'm managing a single source code for different outputs based on the language [spanish, basque, ...], and based on the format pdf vs html, etc. Hence, one solution I found was to hack the output file name and use different output directories for different types of format/languages.

That worked just fine until I changed from website to book (I want a single PDF, not a bunch of them). The aim is to cross reference between different chapters/pages automatically.

Nevertheless, I don't know if I will be able to patch that myself, or achieve the same goal using other tricks. But, I think that "output-file" cannot be used in chapters for cross-referencing in html to work\ is a simple message that could be at least in the documentation.

That answers your question? Thanks for the interest.

[mcanouil]

(I want a single PDF, not a bunch of them).

But, I think that "output-file" cannot be used in chapters for cross-referencing in html to work

Sorry, but do you want one or several? Setting output-file at the chapter level means you want several documents, but you just said you want only one.
You got me confused on your goal here.

If your goal is to produce a PDF/Website in Spanish, Chinese, French, then set output-file at the project level as described in the documentation on books that I've linked in my previous reply.
If not already, using project profiles can also help with this. (there are quite few examples in the discussion board about multilingual books)

edit: follow/read the following issue:

• Multilingual websites / books #275

To be clear, I'm not saying there is nothing to be improved.

[cderv]

@iagobaapellaniz Could you share a full book project with your setup so that we can try replicate ?

It could indeed be that setting output-file in a chapter is messing up the section cross-reference. I am not sure such a case is expected, and really not sure how setting output-file behaves for chapters in a Book. I am quite sure that could cause issue for HTML book (multifile output) vs PDF book (single file output).

Probably we need to protect against this type of usage in Quarto.

More details will be helpful - Thanks for your help!

[iagobaapellaniz]

@cderv I send you a minimal working example lbxubnbupzvgoc18

[mcanouil]

@iagobaapellaniz Would you mind sharing a Git repository?

[cderv]

@mcanouil the shared files will do. Thank you @iagobaapellaniz !

[iagobaapellaniz]

Sorry, but do you want one or several? Setting output-file at the chapter level means you want several documents, but you just said you want only one. You got me confused on your goal here.

I want a single PDF, but one HTML file per chapter. Hence, for managing the languages I mainly work with profiles and skip rendering *.eu.qmd for the spanish version and skip rendering *.es.qmd for the basque version (second pass). The thing is that, I render each pass/language in different folders, let's say /es/ and /eu/. If I would run the second pass on top of the first one it would be deleted.

@iagobaapellaniz Would you mind sharing a Git repository?

I don't have any yet. Certainly I will share one whenever I have one ready. What I have is a website project that does what I want, but it is not a book https://gitlab.com/Eduki/pocalculo

[cderv]

Thanks for the additional informations.

You are trying to come up with your own system for

• Multilingual websites / books #275

For context, if you want inspiration, look at babelquarto: it is an R package that does some handling around Quarto project to use a multilingual book and website: https://docs.ropensci.org/babelquarto/
Live example is this book made with Quarto: https://devguide.ropensci.org/ with a spanish version at https://devguide.ropensci.org/

That being said, I can reproduce what you see. Setting output-file inside a chapter will modify the output filename, but section references are not handled. So we don't handle this kind of tweak.

I can't promise we'll fix it because I don't know if setting output-file inside a single chapter is something we can safely support. Section reference is probably not the only issue.

I am uploading back the zip you shared for later reference:

reprex book custom name.zip

Hence, for managing the languages I mainly work with profiles and skip rendering *.eu.qmd for the spanish version and skip rendering *.es.qmd for the basque version (second pass).

Looks like a good way !

The thing is that, I render each pass/language in different folders, let's say /es/ and /eu/.

You do change output-dir for that in your profile right ?

If I would run the second pass on top of the first one it would be deleted.

If you use output-dir, I am not sure when you need different file name, as each version of the book will be in its own folder.

[mcanouil]

The thing is that, I render each pass/language in different folders, let's say /es/ and /eu/. If I would run the second pass on top of the first one it would be deleted.

If you know what you are doing, and want both "es" and "eu" be inside your output-dir (default for book project is _book), you have two options:

• Write a post-render script that copy/move the directory to their rightful location.
• use quarto render --no-clean at the risk of keeping outdated things.

[iagobaapellaniz]

If you use output-dir, I am not sure when you need different file name, as each version of the book will be in its own folder.

I think it was mainly for the index.html file, so https://eduki.gitlab.io/pocalculo/eu/ points to the right file index.eu.qmd.

I think that for a book project I can use profile-for-language to avoid having more than a single index (which is also required by book projects)

[mcanouil]

Maybe the solution is with site-url and aliases here.

[iagobaapellaniz]

use quarto render --no-clean at the risk of keeping outdated things.

That's a possible solution! Thanks! I used to have problems only on deployment. For writing the notes, I don't render the whole project. I go language by language. Hence, I don't mind if all of them are rendered or not. Indeed, it takes more time if I render all the languages.

I have to say that Quarto is awesome!!