Using unchanged default TeX template or partials changes output

[gl-eb]

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

Using any TeX partial, even when using the exact same file as Quarto uses by default, changes the .tex file from which the PDF is rendered.

Steps to reproduce

1. Create a new book project

   quarto create project book book-test book-title --no-open
   cd book-test

   Edit the _quarto.yml file by adding keep-tex: true

   project:
     type: book
   
   book:
     title: "book-title"
     author: "Norah Jones"
     date: "7/10/2025"
     chapters:
       - index.qmd
       - intro.qmd
       - summary.qmd
       - references.qmd
   
   bibliography: references.bib
   
   format:
     html:
       theme:
         - cosmo
         - brand
     pdf:
       documentclass: scrreprt
       keep-tex: true

2. Render project using quarto render. This will result in book.tex in the home directory. Rename this file, otherwise it will be overwritten by the next rendering: mv book.tex book_default.tex

3. In the home directory, create an empty file which will act as a TeX template partial. For this example I've chosen the before-title.tex partial, which is empty by default.

   touch before-title.tex

   Set the project to use the partial by setting template-partials. The _quarto.yml file now looks like this:

   project:
   type: book
   
   book:
   title: "book-title"
   author: "Norah Jones"
   date: "7/10/2025"
   chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd
   
   bibliography: references.bib
   
   format:
   html:
    theme:
      - cosmo
      - brand
   pdf:
    documentclass: scrreprt
    keep-tex: true
    template-partials:
      - before-title.tex

Actual behavior

Compare the book_default.tex and book.tex files to reveal three changed lines:

% diff book.tex book_partial.tex

9,10c9
<   DIV=11,
<   numbers=noendperiod]{scrreprt}
---
> ]{scrreprt}
138a138
>  
141,142d140
< 
< \KOMAoption{captions}{tableheading}

• The DIV=11 and numbers=noendperiod options are gone from the \documentclass[...]{scrreprt} call when using any partial
• The following line is missing completely when using any partial: \KOMAoption{captions}{tableheading}

I was able to reproduce this behaviour when using the default template file template: template.tex or other partials like template-partial: title.tex.

In particular the DVI=11 option changes the text area of the PDF, which results in noticeably different text width and thus (when enough text is present in the book) document length.

Expected behavior

The two files should be identical when using default partials, particularly when both the default and user-supplied partial files are empty.

Nota bene, this behaviour does not occur when using quarto render --to latex instead of quarto render with the keep-tex: true option.

Your environment

Positron Version: 2025.07.0 build 204
Code - OSS Version: 1.100.3
Commit: 03ae7a5393c776bb24c23d2aa6a6bfbba90cbc5e
Date: 2025-06-30T16:29:03.492Z
Electron: 34.5.1
Chromium: 132.0.6834.210
Node.js: 20.19.0
V8: 13.2.152.41-electron.0
OS: Darwin arm64 24.5.0

Quarto check output

% quarto check
Quarto 1.7.32
[✓] Checking environment information...
      Quarto cache location: /Users/gleb/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: (external install)
      Chromium: (not installed)

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

[✓] Checking Chrome Headless....................OK
      Chrome:  (not detected)

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

[✓] Checking Python 3 installation....OK
      Version: 3.13.2
      Path: /Users/gleb/.pyenv/versions/3.13.2/bin/python3
      Jupyter: (None)

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

[✓] Checking R installation...........OK
      Version: 4.4.3
      Path: /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources
      LibPaths:
        - /Users/gleb/Library/R/arm64/4.4/library
        - /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/library
      knitr: 1.48
      rmarkdown: 2.28

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

[mcanouil]

Not saying, this is or not a bug, but partials are not in place replacement.
Using a partial means: I will take the processing of this part on my end and don't want Quarto to do anything it usually does on this part.

You can see this in various issues and discussions about using the partials, mostly when trying to use authors/affiliations.

[gl-eb]

Not saying, this is or not a bug, but partials are not in place replacement. Using a partial means: I will take the processing of this part on my end and don't want Quarto to do anything it usually does on this part.

You can see this in various issues and discussions about using the partials, mostly when trying to use authors/affiliations.

I see, it was not clear to me that using custom partials could have an impact outside of their immediate scope.

Diving further into the behaviour, it looks like this logic is responsible and is working as intended. It seems the additional options passed to \documentclass are only added when the user documentclass is not set to any of the KOMA-script classes as well as when template or template-partials are used.
I can understand why this logic was implemented and it is possible to pass the options to \documentclass using classoption in _quarto.yml. I was just thrown off because it was not evident why this was happening before I dove into the Quarto logic.

Maybe the documentation can be ammended to state that using partials might have unforseen effects outside of what the partial itself if about?

[cscheid]

Maybe the documentation can be ammended to state that using partials might have unforseen effects outside of what the partial itself if about?

I appreciate the perspective and concrete proposal, but I think we need to be a little careful here.

The amendment you're proposing would be useful for you because you happened to have an inaccurate assumption about the behavior of partials. I would like to see evidence that this inaccurate assumption is more widespread in our userbase before adding a specific warning like that (otherwise, our documentation would eventually be mostly about specific warnings for specific users).

[cderv]

Thanks for the report. This is indeed surprising behavior. We don't document it clearly in the Koma section
https://quarto.org/docs/output-formats/pdf-basics.html#document-class

You found the logic that causes this behavior

quarto-cli/src/format/pdf/format-pdf.ts

Lines 168 to 185 in 6e36833

	const usingCustomTemplates = format.pandoc.template !== undefined ||
	format.metadata[kTemplatePartials] !== undefined;
	if (
	usingCustomTemplates ||
	(documentclass &&
	![
	"srcbook",
	"scrreprt",
	"scrreport",
	"scrartcl",
	"scrarticle",
	].includes(
	documentclass,
	))
	) {
	koma = false;
	}

I don't have a linked issue, but I would guess this change was made as using Koma is an opinionated choice for the default for Quarto. This works for sure with our templates, but could cause issues with non-default templates. Hence, the detection and removal.

At least, we could add something to the doc. I don't know if we can be more clever (like only setting to false when some known partials are passed)

[cderv]

@cscheid I posted same time as you sorry.

I was thinking we should just add a mention in https://quarto.org/docs/output-formats/pdf-basics.html#document-class that Koma will be used as the default, unless a custom template or partials are used. In that case, the user tweaking templates needs to adapt documentclass and options

[gl-eb]

Thanks both @cscheid and @cderv for replying. I agree that not every possible misunderstanding of Quarto's behaviour should be explained in the documentation.

However, in this case not only does Quarto have a default document class, it also sets additional options and changes an additional setting, which is not evident from the default template and partial files. I am perfectly fine not documenting every customisation that Quarto makes to Pandoc defaults, but in this case a user would have to even go beyond .tex files and look at Quarto logic written in typescript to understand what is going on.

I'm not sure myself what the best course of action here is. Obviously you cannot and should not provide documentation and configuration for every minute detail. In any case, thanks for hearing me out.

[cscheid]

I was thinking we should just add a mention in https://quarto.org/docs/output-formats/pdf-basics.html#document-class that Koma will be used as the default, unless a custom template or partials are used. In that case, the user tweaking templates needs to adapt documentclass and options

I think this is a good change.