PDF Format extension: How to change header declaration contents (include-in-header: header.tex) based on YAML value / How to declare two custom formats both extending from the same base-format in the same extension?

[Claudius-Appel]

Description

Hello,

I am currently porting the thesis latex template my university provides to quarto.

To that end, I have declared the _extension.yml:

# _extension.yml
title: Msc-AngewandteBioinformatik-format-ext
author: Claudius Appel
version: 1.0.0
quarto-required: ">=1.5.0"


contributes:
    formats:
        common:
        filters:
            - ...
            - ...
        pdf:
            ...
            include-in-header: 
                - tex/header-print.tex

            ## BIBLIOGRAPHY AND CITATION HANDLING
            ...

            format-resources:
                - meta/cleanthesis.sty
                ...
            template-partials:
                - "tex/partials/pandoc/passoptions.latex"
                ...
        msc-angewandtebioinformatik-format-ext-pdf:
            language:
                crossref-lst-prefix: P.
                crossref-fig-prefix: Abb.
                crossref-tbl-prefix: Tab.
            ...

The latex-template I am modelling sets in their preamble the following:

% **************************************************
% Document Class Definition
% **************************************************
\documentclass[%
    ...
]{scrreprt}%

% \usepackage[utf8]{inputenc} 
% ! important for correct colors (embeds icc profile used for logos and stuff, otherwise colors wont match)
\usepackage[x-4]{pdfx}%
\setRGBcolorprofile{FOGRA29_ISOuncoated.icc}{FOGRA29}{cmyk}%

% **************************************************
% Setup YOUR thesis document in this file !
% **************************************************
\input{my-thesis-setup}
 

% **************************************************
% Document CONTENT
% **************************************************
\begin{document}
...

Notable here is that they configure x-4 as the pdf standard via \usepackage[x-4]{pdfx}, which will purposely break digital in-document linkage. This breaks:

• Population of the ToC
• Links in ToC,
• "List of X",
• cross-references to figures, tables, etc in the document,
• cross-references to citations and appendix-contents,
• probably other stuff

all do not work. This is in line with the reference I am targeting, so strictly speaking this is fine. Therefore I have incorporated this into the header-print.tex.

My issue is that during writing of a document - where everything is done digitally anyways - having to forego the usage of clickable cross-references is time-consuming and hinders productivity¹.

---

Therefore it would be sensible to work with a different pdf-standard during writing. I currently use \usepackage[a-2b]{pdfx} to preserve the features breaking under x-4 when working digitally².

The question is how to incorporate this.

\usepackage-commands must be issued in the document header. To my knowledge, I cannot parse YAML-/frontmatter data at that point. This means I cannot use conditionals to control which pdf-standard is applied. The consequence is that I have to use two different header-files.
But to include them exclusive to each other; the only idea I have found so far is to declare two different extensions; because I cannot control dynamically what in-header-include is used.

Unfortunately, it seems I cannot just declare both formats in the same extension, i.e. setting

• _extension.yml:

  contributes:
      formats:
          pdf:
              # stuff
              ...
              format-resources:
                  - meta/cleanthesis.sty
                  ...
              template-partials:
                  - "tex/partials/pandoc/passoptions.latex"
                  ...
          msc-angewandtebioinformatik-format-ext-pdf:
              include-in-header: 
                  - tex/header-print.tex
          msc-digital-pdf:
              include-in-header: 
                  - tex/header-digital.tex

• header-print.tex:

  ...
  \usepackage[x-4]{pdfx}
  \setCMYKcolorprofile{gfx/FOGRA29_ISOuncoated.icc}{FOGRA29}{cmyk}{<http://www.color.org}>
  ...

• header-digital.tex:

  ...
  \usepackage[a-2b]{pdfx}
  \setCMYKcolorprofile{gfx/FOGRA29_ISOuncoated.icc}{FOGRA29}{cmyk}{<http://www.color.org}>
  ...

• testfile.qmd

  ---
  ... # other stuff
  format: 
  msc-angewandtebioinformatik-format-ext-pdf:
      keep-tex: false
  msc-test-pdf:
      keep-tex: true
  ---
  
  {{< include parts/_template-chapters.qmd >}}
  

will make quarto error out due to an unknown extension:

Claudius Main@Laptop-C MINGW64 /d/Dokumente neu/Repositories/quarto-extensions/Msc-Angewandte-Bioinformatik-quarto-template (feat/true-color-toggle)
$ quarto render testfile.qmd
ERROR: Unable to read the extension 'msc-test'.
Please ensure that you provided the correct id and that the extension is installed.

Stack trace:
    at loadExtension (file:///D:/CLI/quarto/bin/quarto.js:79412:15)
    at Object.extension (file:///D:/CLI/quarto/bin/quarto.js:78618:30)
    at readExtensionFormat (file:///D:/CLI/quarto/bin/quarto.js:91414:50)
    at resolveFormats (file:///D:/CLI/quarto/bin/quarto.js:91273:37)
    at async renderContexts (file:///D:/CLI/quarto/bin/quarto.js:91063:20)
    at async renderFileInternal (file:///D:/CLI/quarto/bin/quarto.js:136916:16)
    at async renderFiles (file:///D:/CLI/quarto/bin/quarto.js:136833:9)
    at async render (file:///D:/CLI/quarto/bin/quarto.js:142487:19)
    at async _Command.actionHandler (file:///D:/CLI/quarto/bin/quarto.js:142732:24)
    at async _Command.execute (file:///D:/CLI/quarto/bin/quarto.js:102143:7)

---

The docs under https://quarto.org/docs/extensions/formats.html#overview, nor any of the format extensions shown under https://github.com/quarto-journals/#quarto-journal-templates have applicable examples (at a quick glance).

The docs on custom formats (as well as on Journal Formats: https://quarto.org/docs/journals/formats.html#common-metadata) talk about declaring multiple formats, but according to docs they must be derived from distinct base formats. This suggests that you cannot declare two custom formats both inheriting from pdf.

Actually, it seems like the directory containing the _extension.yml must bear the same name as the declared format (sans the base-format-suffix, e.g. msc-angewandtebioinformatik-format-ext); which seems to be the limiting problem here.

---

Overall this means I have just declared two extensions which are complete duplicates of each other, excepting the declaration under include-in-header:.

This seems to be an architectural problem to me. The current workaround is viable; but obviously not desirable.

So the question is:

1. Is there a way to do YAML-conditional includes within a include-in-header-ed header.tex-file?
2. If not: Is it possible to declare two format extensions both based on the same base format within the same extension?
3. If not: is there any other solution I have not found, not considered that is more sensible than just straight up duplicating the format extension?

---

Side-question that is semi-related:

Without setting up a (website) project, declaring two profiles and associating the rendering to either format with a profile each; is there a way to namespace the generated .pdf-files? I.e. to have thesis-digital.pdf and thesis-print.pdf as outputs, based on what format was rendered?

Currently, if I were to use both extensions and had to render; I would have to set up profiles in order to set two different output-dir to preserve both instances simultaneously. Is there a different way to generate both targets so they coexist?

---

Thank you.

Claudius

Footnotes

1. besides this I would assume grading the digital instance is easier with working links, but that is not on me to decide/leverage ↩

2. This in turn breaks color-accuracy, but I have yet to find a color-accurate standard which preserves links; and am ignoring this side-problem for now. ↩

[mcanouil]

Quarto has had a built-in pdf-standard option since 1.9, so you do not need the pdfx package, a conditional header.tex, or a second extension.

Use pdf-standard

• thesis.qmd

  ---
  title: "Thesis"
  format:
    thesis-pdf:
      pdf-standard: a-2b
  ---

Quarto turns that into a \DocumentMetadata{...} call at the very top of the LaTeX file, which is the modern LaTeX mechanism for conformance and largely supersedes pdfx.
I checked this on a small thesis-like extension: with pdf-standard: x-4 the preamble contains no pdfx at all, and the resulting PDF still carries its link annotations.
That is the behaviour you lost, so this alone may be the whole answer for you.

Points worth knowing:

• It needs LuaLaTeX and a LaTeX distribution from 2023 or later.
• x-4 and the other PDF/X values are LaTeX only; a-* values work for both LaTeX and Typst. An unsupported value produces a warning and is ignored.
• The PDF version is inferred where the standard requires one, so a-2b gives you pdfversion=1.7 for free.
• You can pass a list, for example pdf-standard: [a-2b, ua-2] for an archival and accessible PDF. A ua-* value turns LaTeX tagging on.
• QUARTO_PDF_STANDARD=x-4 works as an environment fallback if you would rather not touch the YAML, which is handy in CI.
• quarto install verapdf adds veraPDF, and Quarto then validates conformance automatically after each render.

Two variants, two file names, one extension

Set the standard per format key and add a modifier to the second entry:

• thesis.qmd

  ---
  title: "Thesis"
  format:
    thesis-pdf:
      pdf-standard: a-2b
    thesis-pdf+print:
      pdf-standard: x-4
  ---

The modifier does not have to be declared by the extension.
Quarto looks up pdf+print in the extension and falls back to the pdf key, so both entries use the same contributed format.

For PDF, Quarto already puts variants and modifiers into the output name, so this writes thesis.pdf and thesis+print.pdf from a single quarto render, with nothing further to configure.
See the notes on filenames with modifiers.
If you want your own names, add output-file:

• thesis.qmd

  format:
    thesis-pdf:
      pdf-standard: a-2b
      output-file: thesis-digital.pdf
    thesis-pdf+print:
      pdf-standard: x-4
      output-file: thesis-print.pdf

A dash does not work for this. thesis-pdf-print is split on the last dash, so Quarto would look for an extension named thesis-pdf.

If you would rather the extension carried the two presets, use the same +modifier syntax on the keys:

• _extensions/thesis/_extension.yml

  title: Thesis
  version: 1.0.0
  quarto-required: ">=1.9.0"
  contributes:
    formats:
      common:
        toc: true
        format-resources:
          - thesis.cls
      pdf:
        pdf-standard: a-2b
      pdf+print:
        pdf-standard: x-4

common is merged into every other key, so shared options are written once.
Note that the lookup is a fallback and not a merge: pdf+print does not inherit from pdf, so anything shared belongs in common.

On the general questions

Can include-in-header be conditional?
No.
The files are handed to pandoc and interpolated verbatim into the header-includes variable, and pandoc does not re-evaluate that value as a template, so $if(...)$ comes out as literal text.

Two things do give you conditionals, if you ever need one for something pdf-standard does not cover:

• Template partials are compiled as pandoc templates, so $if(...)$ works inside a replacement doc-class.tex, hypersetup.latex, and so on. The cost is that you now own that partial.

• A Lua filter keeps Quarto's template intact:

  • _extensions/thesis/thesis.lua

    function Meta(meta)
      if quarto.doc.is_format("pdf") and meta["print"] then
        quarto.doc.include_file("in-header", "print.tex")
      end
    end

  quarto.doc.include_file(location, file) resolves the path relative to the Lua script, so the .tex files sit next to it in the extension.
  quarto.doc.include_text(location, text) and quarto.doc.use_latex_package(pkg, opts) are the other two; the valid locations are in-header, before-body and after-body (Lua API).
  Content injected at in-header lands before Quarto's template loads bookmark (and so hyperref), which is what you want for anything that has to precede hyperref.

Do you have to duplicate the extension?
No, and even if you did want two separate formats, one repository can hold several extension directories, all installed by a single quarto add owner/repo:

thesis/
└── _extensions/
    └── your-org/
        ├── thesis-digital/_extension.yml
        └── thesis-print/_extension.yml

They are used as thesis-digital-pdf and thesis-print-pdf, and a user can install just one with quarto add owner/repo/thesis-print.
The directory name has to match the part before the last dash, which is the constraint you hit.
See distributing extensions.

[Claudius-Appel]

Thank you for the reply, this has mostly got me running.

As background for the rest of this reply:
I am trying to set custom metadata variables per-format, such that I can differentiate them between the msc-angewandtebioinformatik-format-ext-pdf and msc-angewandtebioinformatik-format-ext-pdf+print-versions. Specifically, I need two different value-sets for

contributes:
  formats:
    common:
      linkcolor: purple
      filecolor: purple
      citecolor: purple
      urlcolor: purple
      toccolor: purple

and for a custom dict

contributes:
  formats:
    common:
      jgu-meta:
        features: #*
          titlepageShowGraphicElement: show # show/hide
          declareAllowedAITools: true # true/false
          titlepageHeight: 6cm
          titlepageStart: 8cm
          colorTheme: jgured # jgured/bluegreen/bluemagenta
          colorLinks: true # false/true
        thesisPrimary: #+
          thesisTitle: TITEL DEINER THESE
          thesisAuthor: YOUR NAME
          thesisBirthplace: LOCATION
          thesisSubject: THEMA DEINER THESE
          # keywords: see global keywords toggle.
        thesisUniversity: #* 
          Name: UNIVERSITY FULL NAME
          Department: FBXX
          DepartmentLong: FACULTY OF X, Y, Z
          Institute: INSTITUTE OF COMPUTER SCIENCE
          ResearchGroup: YOURRESEARCHGROUP
          City: LOCATION
          StreetAddress: STREET AND NUMBER
          PostalCode: POSTAL

Since I need (some of these) values differentiated when declaring stuff in toc.tex (or just in general); I have been trying to figure out how to do that.

A few things I am very confused about though; which stems from me continuing from here.

common is merged into every other key, so shared options are written once.
Note that the lookup is a fallback and not a merge: pdf+print does not inherit from pdf, so anything shared belongs in common.

Given the following _extension.yml:

contributes:
  formats:

    common:
      number-depth: 2
    #   toc: true

    pdf:
      keep-tex: true
    #   toc: true

    msc-angewandtebioinformatik-format-ext-pdf:
      toc: true

    msc-angewandtebioinformatik-format-ext-pdf+print:
      toc: false

It seems that the configurations under msc-angewandtebioinformatik-format-ext-pdf(+print) never applies - even if I remove toc: true from common, pdf, or both.

Am I just completely missing something? Because the way I understand the docs on common metadata, as well as your comment cited above; I'd assume either of the following to be true:

1. common metadata can be overwritten in a format-extension based upon it. If multiple formats are declared in the extension; and not all of them declare that key, the default declared under common is kept.
2. (All) keys in common are immutable, and re-declarations under a custom format will not hold.

pdf+print does not inherit from pdf, so anything shared belongs in common

My understanding: By inversion this should mean that stuff can not be shared, by declaring it only in myformat-pdf+print and myformat-pdf. If that key is then not in common, it should be read from myformat-pdf+print and myformat-pdf respectively.

But that doesn't happen. If I declare toc: true in myformat-pdf+print and myformat-pdf, but not in common or pdf:

contributes:
  formats:
    common:
      # toc: true
    pdf:
      # toc: true
    msc-angewandtebioinformatik-format-ext-pdf:
      toc: false

    msc-angewandtebioinformatik-format-ext-pdf+print:
      toc: false

then it just doesn't show up in the command output:

$ quarto render testfile.qmd --to msc-angewandtebioinformatik-format-ext-pdf
pandoc
  to: latex
  output-file: testfile.tex
  standalone: true
  embed-resources: true
  pdf-engine: lualatex
  variables:
    graphics: true
    tables: true
    secnumdepth: 2
  default-image-extension: pdf
  top-level-division: default
  cite-method: biblatex
  number-sections: true
  reference-location: document

If I declare toc: true in pdf now, I get

$ quarto render testfile.qmd --to msc-angewandtebioinformatik-format-ext-pdf
pandoc
  to: latex
  output-file: testfile.tex
  standalone: true
  embed-resources: true
  pdf-engine: lualatex
  variables:
    graphics: true
    tables: true
    secnumdepth: 2
  default-image-extension: pdf
  top-level-division: default
  toc: true
  cite-method: biblatex
  number-sections: true
  reference-location: document

and if I instead declare it in common (and not in pdf); I get

$ quarto render testfile.qmd --to msc-angewandtebioinformatik-format-ext-pdf
pandoc
  to: latex
  output-file: testfile.tex
  standalone: true
  embed-resources: true
  pdf-engine: lualatex
  variables:
    graphics: true
    tables: true
    secnumdepth: 2
  default-image-extension: pdf
  top-level-division: default
  toc: true
  cite-method: biblatex
  number-sections: true
  reference-location: document

This means that declarations in pdf and common supersede declarations under msc-angewandtebioinformatik-format-ext-pdf(+print) in _extension.yml.

Am I misunderstanding the way merging should apply?

---

This actually becomes even more confusing:

Take the following testfile.qmd

---
# ...
format: 
  # html: default
  msc-angewandtebioinformatik-format-ext-pdf+print:
    keep-tex: true
    # toc: false
  msc-angewandtebioinformatik-format-ext-pdf:
    keep-tex: false
    # toc: false
---

{{< include parts/_abstracts.qmd >}}
<!-- {{< include parts/syntax-tests/_tests.qmd >}} -->
{{< include parts/_template-chapters.qmd >}}

and this modified _extension.yml:

contributes:
  formats:
    common:
      toc: true
    pdf:
      # toc: true
    msc-angewandtebioinformatik-format-ext-pdf:
      toc: false

    msc-angewandtebioinformatik-format-ext-pdf+print:
      toc: false

right now, this applies toc: true from common:

Claudius Main@Laptop-C MINGW64 /d/Dokumente neu/Repositories/quarto-extensions/JGU-Msc-Angewandte-Bioinformatik-quarto-template (feat/implement-print-digital-split)
$ quarto render testfile.qmd --to msc-angewandtebioinformatik-format-ext-pdf+print
pandoc
  to: latex
  output-file: testfile+print.tex
  standalone: true
  embed-resources: true
  pdf-engine: lualatex
  variables:
    graphics: true
    tables: true
    secnumdepth: 2
  default-image-extension: pdf
  top-level-division: default
  toc: true

but if I set format.msc-angewandtebioinformatik-format-ext-pdf+print.toc: false in testfile.qmd; that change does apply successfully¹:

$ quarto render testfile.qmd --to msc-angewandtebioinformatik-format-ext-pdf+print
pandoc
  to: latex
  output-file: testfile+print.tex
  standalone: true
  embed-resources: true
  pdf-engine: lualatex
  variables:
    graphics: true
    tables: true
    secnumdepth: 2
  default-image-extension: pdf
  top-level-division: default
  toc: false
  cite-method: biblatex
  number-sections: true
  reference-location: document

So:

1. In _extension.yml:
   1. Format-keys under myformat-pdf and myformat-pdf+print do not apply at all, even if they are unset under pdf and common.
   2. Format-keys under pdf and common always apply. If they are not set, seemingly quarto's defaults for pdf take hold (I am not sure here?)
2. In file.qmd:
   1. Format-keys under format.myformat-pdf and format.myformat-pdf+print supersede declarations under pdf and common in _extension.yml
3. In _metadata.yml:
   This file applies the same behaviour as described for file.qmd under point 2.

Consequently, I can declare invalid values toc: bogus in myformat-pdf(+print) in _extension.yml and have a successful compile, but can not do so in file.qmd or _metadata.yml².

So, I am fairly confused as to why this - to me inconsistent - behaviour occurs.

Am I just... utterly lost?

---

To a lesser extend, I am also lost as to how I should go about declaring custom metadata on a per-format basis; that is how I would go about bundling two states of jgu-meta-section shown at the beginning of this reply; where each state associates with either the msc-angewandtebioinformatik-format-ext-pdf or msc-angewandtebioinformatik-format-ext-pdf+print-format; and how to access them in tex-partials (most likely hypersetup.latex/passoptions.latex; and toc.tex).
The intention is that these would have two different setups out of the box; but should remain configurable by the user. So... yea.

I guess alternatively one could try and detect the presence/absence of +print-modifier

• during hypersetup.latex (is that info even exposed to tex?)
• via a filter which would then insert additional data into the in-header-section via quarto.doc.include_file("in-header", "snippet.tex"); which then could inject the stuff.

Both of these ideas hinge on whether or not

• the modifier is differentiable (it is, I have already implemented an extension checking against this)
• I can figure out a way to package the metadata into the format declaration such that it encodes the color setups I need, while somehow being adjustable user-sided. So that would mean making the filter read frontmatter for presence/absence of a key targeting alternative paths to read and ingest instead, most likely. The downside here is that users would then have to write these tex-files themselves in order to modify them; or I'd need to figure out some parser as well.

---

Thank you.

---

Since this is becoming more convoluted:

$ quarto check
Quarto 1.10.14
[>] Checking environment information...
      Quarto cache location: C:\Users\Claudius Main\AppData\Local\quarto
[>] Checking versions of quarto binary dependencies...
      Pandoc version 3.8.3: OK
      Dart Sass version 1.87.0: OK
      Deno version 2.7.14: OK
      Typst version 0.14.2: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
      Version: 1.10.14
      Path: D:\CLI\quarto\bin
      CodePage: 1252

[>] Checking tools....................OK
      TinyTeX: (external install)
      Chromium (deprecated): 869685
            (Run "quarto install chrome-headless-shell" to replace)
      Chrome Headless Shell: (not installed)
      VeraPDF: (not installed)

[>] Checking LaTeX....................OK
      Using: Installation From Path
      Path: D:\CLI\tinytex\bin\windows
      Version: 2026

[>] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: C:\Program Files\Google\Chrome\Application\chrome.exe
      Source: Windows Registry

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

[>] Checking R installation...........OK
      Version: 4.6.0
      Path: D:/CLI/r/R-4.6.0
      LibPaths:
        - D:/Dokumente neu/Repositories/quarto-extensions/JGU-Msc-Angewandte-Bioinformatik-quarto-template/renv/library/windows/R-4.6/x86_64-w64-mingw32
        - C:/Users/Claudius Main/AppData/Local/R/cache/R/renv/sandbox/windows/R-4.6/x86_64-w64-mingw32/9b05b2bb
      knitr: 1.51
      rmarkdown: 2.31

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

[>] Checking Python 3 installation....(None)

      Unable to locate an installed version of Python 3.
      Install Python 3 from https://www.python.org/downloads/

[>] Checking Julia installation...

Footnotes

1. unlike declarations in _extension.yml under the same key-nesting ↩

2. as that would crash ↩