output-file naming is not used for docx-book

[dmenne]

Bug description

File name in Word/Book output is always derived from title.

Steps to reproduce

• Create a standard book as in https://quarto.org/docs/books/
• Replace in _quarto:

format:
  docx:
    output-file: "IWantThisName"
    output-ext: "docx"

Expected behavior

Output file name should be IWantThisName.docx

Actual behavior

Output file name is mybook.docx

Your environment

No response

Quarto check output

Also tested with 1.7.13

C:\tmp\mybook>quarto check
Quarto 1.6.40
[>] Checking environment information...
      Quarto cache location: C:\Users\Dieter\AppData\Local\quarto
[>] Checking versions of quarto binary dependencies...
      Pandoc version 3.4.0: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.46.3: OK
      Typst version 0.11.0: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
      Version: 1.6.40
      Path: C:\Users\Dieter\AppData\Local\Programs\Quarto\bin
      CodePage: 1252

[>] Checking tools....................OK
      TinyTeX: v2025.02
      Chromium: (not installed)

[>] Checking LaTeX....................OK
      Using: TinyTex
      Path: C:\Users\Dieter\AppData\Roaming\TinyTeX\bin\windows\
      Version: 2024

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

[>] Checking Python 3 installation....OK
      Version: 3.13.1
      Path: C:/Users/Dieter/AppData/Local/Programs/Python/Python313/python.exe
      Jupyter: (None)

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

[>] Checking R installation...........OK
      Version: 4.4.2
      Path: C:/PROGRA~1/R/R-44~1.2
      LibPaths:
        - C:/Program Files/R/R-4.4.2/library
      knitr: 1.49
      rmarkdown: 2.29

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

[mcanouil]

I don't think book project support this at all or ever supported it contrary to the option being listed in the reference page for book.

output-file does not work for any book related formats in any version of Quarto CLI (>=1.0.38).

I suggest to use post-render instead: Pre and Post Render project scripts

[dmenne]

Post-render is what I am using, but it is ugly to rename

The_relation_between_gastric_emptying_parameters_and_secondary_measures_of_digestion_with.docx

To

Gastric_emptying_20_01_2025.docx

Ok, I can use QUARTO_PROJECT_OUTPUT_DIR etc. But please, put this into the docs, I tried hours until I gave up.

[cderv]

I think this is a valid use case to support as docx, epub and pdf will be one file output for book. So using output-file to rename makes sense.

The logic would be to use book.title is output-file is not set, and use output-file value otherwise 🤔

I need to think if this could have unexpected side effect to do such thing - if we can scope to book context, I think that should be fine.

post-render is currently the way to deal with that. We'll see where to put that in the doc.

[cderv]

I don't think book project support this at all or ever supported it contrary to the option being listed in the reference page for book.

I missread this sorry.

output-file is indeed listed in the reference in this section: https://quarto.org/docs/reference/projects/books.html#section

This is a book key, meaning it is a specific book project key.

book:
  title: "Title of the book"
  output-file: "custom-book-name"

It works ok with latest Quarto, and we'll be use instead of title when provided.

It can't be specified per format. If you need to have different name for different format, then you need to leverage Project profile to be able to change the book.output-file key.

I'll see if I can improve the doc to make this option findable.

[dmenne]

You are right. For the user, it's often difficult to find out on which level some key should be given. When you given a key in a wrong first level, Intellisense will work fine to reject it. Not in this case.

[mcanouil]

I read again what I wrote and it's actually not very clear.

I meant: "this" and "it" refer to "output-file under format" in:

I don't think book project support this at all or ever supported it.

I (wrongly?) assumed the per format was a requirement, thus did not mention explicitly:

book:
  output-file: "custom-book-name"

[cderv]

@dmenne Using output-file under book config key is documented in there:
https://quarto.org/docs/books/book-output.html#output-path

It is in "Customizing Book Output" part so it seems pretty clear.
Did you found this ? Do you think it should be elsewhere ?

I meant: "this" and "it" refer to "output-file under format" in:

@mcanouil So when you said "contrary to the option being listed in the reference page for book." you meant book.output-file ?

In that case, this is all good. I completely missed that from your comment. Sorry

output-file per format is really something for single document, and not project. It has a lot of implication in our codebase. So I don't think we would support easily setting output-file per format for book project (quick try showed the complication).

All the more because using Profiles probably works well enough. One profile per book title desired, with the desired format for the book title in each profile.

[mcanouil]

@mcanouil So when you said "contrary to the option being listed in the reference page for book." you meant book.output-file ?

Yes, but I was not very clear😅

[cderv]

Considering our Book part of the doc already mention the option at quarto.org/docs/books/book-output.html#output-path

and this is already in the reference, I just added docx specifically as applied format for the option.

Regarding the use case and the documentation of how to change title to a book, this is a good topic for a blog post a simple recipe. I'll make a note of this.