Unexpected behavior: Quarto is altering font name values in _extension.yml

[connorferster]

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

I am creating a new Quarto format as a custom extension. Everything is working great when I put all of the font configuration information at the beginning of my .qmd or .ipynb file. However, when I put the default configuration in my "_environment.yml" "_extension.yml" file then some funny stuff happens.

Here is the contents of my "_extensions" dir:

_extensions/
├─ extension_name/
│  ├─ CaskaydiaCove/
│  ├─ Ubuntu/
│  ├─ template.tex
│  ├─ _extension.yml

I am including font files in my extension (see "Ubuntu" and "CaskaydiaCove", above) for use with my Latex template ("template.tex").

The problem occurs when I populate my "_environment.yml" "_extension.yml" file with my default values. Here is an MWE of my "_environment.yml" "_extension.yml" file:

title: extension_name
author: Me
version: 0.0.1
contributes:
  project:
    project:
      type: book
  formats: 
    pdf:
      toc: false
      number-sections: false
      template: template.tex
      font-paths:
        main: _extensions/extension_name/Ubuntu
        code: _extensions/extension_name/CaskaydiaCove
      catch: # This key chosen to demonstrate that the keys do not mater
        main:
          name: Ubuntu # <----- THIS VALUE GETTING SUBSTITUTED
        code:
          name: "CaskaydiaCove" # <------- THIS VALUE GETTING SUBSTITUTED

When I run Quarto with my extension, then the extensions front-matter values are echoed to the terminal. Here is what I am seeing:

metadata
  block-headings: true
  font-paths:
    main: _extensions/engpdf/Ubuntu
    code: _extensions/engpdf/CaskaydiaCove
  catch:
    main:
      name: _extensions/engpdf/Ubuntu # <---- THIS IS NOT THE VALUE I PROVIDED
    code:
      name: _extensions/engpdf/CaskaydiaCove # <---- NEITHER IS THIS ONE

Is this behaviour documented anywhere? When I put this front-matter in my document, the values come through as expected. It's just when I exclude the front-matter configuration for my extension in the doc and allow the "_environment.yml" "_extension.yml" default values to be used when this problem occurs.

Any thoughts?

Steps to reproduce

1. Create a new extension with folder structure as above and with an "_environment.yml" "_extension.yml" file as shown above
2. Create a new .qmd file with the following front-matter:

---
format: extension_name-pdf
---

3. Run quarto and notice that any key that has a value equal to the name of a font directory is going to have its value substituted for the path of the font directory.

Actual behavior

Value of the font name is substituted for the font directory relative path

Expected behavior

Values remain as written without substitution.

Your environment

• VSCode (no extension)
• popOS (Ubuntu/Debian)
• Quarto v 1.7.32

Quarto check output

Quarto 1.7.32
[✓] Checking environment information...
      Quarto cache location: /home/connorferster/.cache/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: /opt/quarto/bin

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

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /home/connorferster/.TinyTeX/bin/x86_64-linux
      Version: 2025

[✓] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: /usr/bin/google-chrome
      Source: PATH

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

[✓] Checking Python 3 installation....OK
      Version: 3.10.12
      Path: /usr/bin/python3
      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]

Unfortunately your example is not reproducible or small.
A lot of pieces are missing which makes it impossible to use.
Please provide a small fully reproducible example and a clear depiction of the steps required to reproduce the issue.

Also quite unclear what is _environment.yml as to my knowledge that's not a Quarto file. (https://quarto.org/docs/projects/environment.html)

---

You can share a self-contained "working" (reproducible) Quarto document using the following syntax, i.e., using more backticks than you have in your document (usually four ````).
See https://quarto.org/bug-reports.html#small-is-beautiful-aim-for-a-single-document-with-10-lines.

If you have multiple files (and if it is absolutely required to have multiple files), please share as a Git repository.

R	Python
````qmd --- title: "Reproducible Quarto Document" format: html engine: knitr --- This is a reproducible Quarto document. {{< lipsum 1 >}} ```{r} x <- c(1, 2, 3, 4, 5) y <- c(1, 4, 9, 16, 25) plot(x, y) ``` {#fig-placeholder} {{< lipsum 1 >}} The end after @fig-placeholder. ````	````qmd --- title: "Reproducible Quarto Document" format: html engine: jupyter --- This is a reproducible Quarto document. {{< lipsum 1 >}} ```{python} import matplotlib.pyplot as plt x = [1, 2, 3, 4, 5] y = [1, 4, 9, 16, 25] plt.plot(x, y) plt.show() ``` {#fig-placeholder} {{< lipsum 1 >}} The end after @fig-placeholder. ````

Additionally and if not already given, please share the output of quarto check within a code block (i.e., using three backticks ```txt), see https://quarto.org/bug-reports.html#check.

[connorferster]

I just reproduced it but it seems I made some typos above.

Here is everything I did to reproduce it.

1. Create a new directory with following structure:

_extensions/
├─ example_extension/
│  ├─ CaskaydiaCove/ # Nothing in here
│  ├─ Ubuntu/ # Nothing in here
│  ├─ template.tex # Empty file
│  ├─ _extension.yml

2. Create the following .qmd file to use the extension:

---
format: example_extension-pdf
---

# Hello world

3. Populate "_extension.yml"" with the following:

title: example_extension
contributes:
  formats: 
    pdf:
      template: template.tex
      font-paths:
        main: _extensions/example_extension/Ubuntu
        code: _extensions/example_extension/CaskaydiaCove
      catch: # This key chosen to demonstrate that the keys do not mater
        main:
          name: Ubuntu # <----- THIS VALUE GETTING SUBSTITUTED
        code:
          name: "CaskaydiaCove" # <------- THIS VALUE GETTING SUBSTITUTED

4. Navigate to the directory with the .qmd file and the new "_extensions" directory and execute:

quarto render example.qmd

And then you will see this echoed to the terminal:

pandoc 
  to: latex
  output-file: example.tex
  template: _extensions/example_extension/template.tex
  standalone: true
  pdf-engine: xelatex
  variables:
    graphics: true
    tables: true
  default-image-extension: pdf
  
metadata
  block-headings: true
  font-paths:
    main: _extensions/example_extension/Ubuntu
    code: _extensions/example_extension/CaskaydiaCove
  catch:
    main:
      name: _extensions/example_extension/Ubuntu # <---- SUBSTITUTED VALUE
    code:
      name: _extensions/example_extension/CaskaydiaCove # <---- SUBSTITUTED VALUE

[mcanouil]

As requested, please share a repository with the files which is simpler than requesting to do a lot of copy/paste.

[connorferster]

Sure:

https://github.com/connorferster/example_extension

[connorferster]

Now this can be reproduced in 15 seconds:

1. Clone repo
2. Navigate inside repo and run quarto render example.qmd
3. Observe stdout echoed from quarto

[mcanouil]

Thanks, to add to this: formats do not matter and the example can be simplified.

Any values in the extension manifest that matches a directory within the extension is extended to full installation path.
This behaviour seems to be on purpose to ease listing resources paths.

This does not happen, if the path given does not match any path from within the extension.

In the end, it seems you are not reporting a bug but asking a question.
As explained in the issue template, questions should be asked on the discussion board rather than in issues.

Elements in the extension manifest are relatives to it, same goes for elements/paths in a project are relative to the project root (defined by _quarto.yml).
It's not explicitly documented but all examples use paths relative to the root extension.

If the matching paths were not expanded to include the current extension path, then the resource wouldn't be accessible to the document/project.

Note that LaTeX adds complexity with how resources, "bst" files, need to be handle by LaTeX, see the various PDF extension already available and the documentation: https://quarto.org/docs/extensions/formats.html#format-resources

[cderv]

Thanks for opening the question.

This is indeed a tricky situation. As explained, Quarto tries to be clever, and it will resolve paths from within the extension when used in a value.

This is so that this can be written

    pdf:
      template: template.tex
      font-paths:
        main: Ubuntu
        code: CaskaydiaCove

And the paths are resolved correctly before being used in the template.

The logic Quarto uses to try to guess what needs to be resolved is: Is there an existing path in the extension root for the value? If so, this is a path value and should be resolved.

So in your case this would mean doing something like this

Doing

    pdf:
      template: template.tex
      font-paths:
        main: fonts/Ubuntu
        code: fonts/CaskaydiaCove
      catch: 
        main:
          name: Ubuntu 
        code:
          name: "CaskaydiaCove"

and moving to

_extensions/
├─ example_extension/
│  ├─ fonts/CaskaydiaCove/ 
│  ├─ fonts/Ubuntu/ 
│  ├─ template.tex 
│  ├─ _extension.yml

Hope this clarifies in addition of previous explanation.