quarto-dev / quarto-dev/quarto-cli

Table of contents title is inserted surprisingly early

Open
#14,786 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement metadata
Dominant language
JavaScript
Stars
6k
Forks
458
Avg merge
1d 9h
Merged PRs (30d)
41

Description

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 would expect a filter to be able to operate on nil metadata in general. This allows an extension to provide reasonable backups for that type. However, a subset of metadata get filled early on in the process, likely linked to metadata with translations.

In particular, this means that items like the toc-title can't have filter-based backups without opting into an "always override" approach (or coming up with special non-standard metadata names).

The label is bug, but I would characterize this somewhere in the surprising behavior spectrum, as it's likely unintended but after searching through the javascript, I can see why it might happen and be hard to make this metadata perform like others.

Steps to reproduce
---
title: "TOC Title Example"
filters:
  - toc-title.lua
toc: true
format: typst
---

## Heading

This filter should have renamed the TOC to "Filter-provided title" because toc-title is not provided.

where toc-title.lua is:


-- replace the title if not provided
function Meta(meta)
  if meta["toc-title"] == nil then
    meta["toc-title"] = pandoc.MetaString("Filter-provided title")
  end
  return meta
end

Actual behavior

The title is "Table of contents".

Expected behavior

The title would be "Filter-provided title".

Your environment
  • IDE: Positron 2026.08.1 build 2
  • OS: Windows 11 Home 25H2
Quarto check output
Quarto 1.10.16
[>] Checking environment information...
      Quarto cache location: C:\Users\chris\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.16
      Path: C:\Users\chris\AppData\Local\Programs\Quarto\bin
      CodePage: 1252

[>] Checking tools....................OK
      TinyTeX: (external install)
      Chrome Headless Shell: (not installed)
      VeraPDF: (not installed)

[>] Checking LaTeX....................OK
      Using: TinyTex
      Path: C:\Users\chris\AppData\Roaming\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.1
      Path: C:/PROGRA~1/R/R-46~1.1
      LibPaths:
        - C:/Users/chris/AppData/Local/R/win-library/4.6
        - C:/Program Files/R/R-4.6.1/library
      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...

(fyi Julia is installed and on path, but the check doesn't emit anything. Seems irrelevant to this issue. Also replicates on 1.10.18.)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the provided Quarto document and toc-title.lua reproducer, then inspect the JavaScript metadata and filter-processing entry points around the Meta filter. Done means a missing toc-title can be supplied by the filter and the rendered Typst table of contents uses "Filter-provided title" without breaking explicitly provided titles.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, lua
Domain
cli
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.