quarto-dev / quarto-dev/quarto-cli

template-partials validation does not catch unsupported partial names

Open
#14,793 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug html revealjs templates
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

When a user supplies template-partials, Quarto validates the names against the format's templateContext.partials and requires only that at least one name matches (pandoc.ts#L803-L830). This check gives wrong results in both directions:

1. format: html — unknown names pass silently.
Quarto injects its own title partials (_title-meta-author.html, title-metadata.html, title-block.html) into the document's template-partials metadata (format-html-bootstrap.ts#L192-L198, via format-html-title.ts#L145-L166). readPartials then returns these injected partials together with the user's list, so the injected title-block.html always satisfies the at-least-one check. A misspelled or unsupported partial name renders with no error and no warning, and has no effect on the output.

2. format: revealjs — the error lists partials that do nothing.
When no name matches, the error says:

ERROR: The format 'revealjs' only supports the following partials:
metadata.html
title-block.html
toc.html
styles.html
toc-slide.html
title-slide.html

The first four names come from the shared HTML format extras (format-html.ts#L631-L642), which mergeConfigs concatenates with the two revealjs partials (format-reveal.ts#L236-L247). But the revealjs template never references metadata.html, title-block.html, or toc.html. If you supply one of them, it passes validation and does nothing. (styles.html is referenced by the revealjs template at template.html#L27 and an override works — but the docs only list title-slide.html and toc-slide.html for revealjs.)

The at-least-one rule also means a typo next to one valid partial passes silently in every format.

An AI assistant helped investigate this issue, grounded in a local clone of quarto-cli (per CONTRIBUTING.md "Using AI tools to investigate").

Steps to reproduce

Case 1 — html accepts an unknown partial name silently.

Create bogus.html with the content <!-- bogus partial -->, and render:

---
title: "partials"
format:
  html:
    template-partials:
      - bogus.html
---

Hello.

Case 2 — revealjs accepts a listed partial that has no effect.

Create metadata.html with the content <!-- custom metadata partial -->, and render:

---
title: "partials"
format:
  revealjs:
    template-partials:
      - metadata.html
---

## Slide

Actual behavior

Both documents render with no error and no warning. Neither HTML comment appears in the output — the supplied partials have no effect. (With revealjs, an unlisted name such as bogus.html does error, but the error lists the four HTML-format partials that revealjs does not use.)

Expected behavior

Quarto reports each supplied partial name that the format's template does not use — not only the case where no name matches. The revealjs error message lists only the partials that have an effect for revealjs.

Your environment

  • IDE: Positron 2026.08.0 build 213 (renders run from its terminal)
  • OS: macOS 26.5.2 (build 25F84)

Quarto check output

Quarto 1.10.18
[✓] Checking environment information...
      Quarto cache location: /Users/charlottewickham/Library/Caches/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.10.0: OK
      Dart Sass version 1.101.0: OK
      Deno version 2.7.14: OK
      Typst version 0.15.1: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.10.18
      Path: /Applications/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: v2026.04
      Chrome Headless Shell: 150.0.7871.115
      VeraPDF: 1.28.2

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

[✓] Checking Chrome Headless....................OK
      Using: Chrome Headless Shell installed by Quarto
      Path: /Users/charlottewickham/Library/Application Support/quarto/chrome-headless-shell/chrome-headless-shell-mac-arm64/chrome-headless-shell
      Version: 150.0.7871.115

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

[✓] Checking R installation...........OK
      Version: 4.6.0
      Path: /Library/Frameworks/R.framework/Versions/4.6/Resources
      LibPaths:
        - /Users/charlottewickham/Library/R/arm64/4.6/library
        - /Library/Frameworks/R.framework/Versions/4.6/Resources/library
      knitr: 1.51
      rmarkdown: 2.31

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

[✓] Checking Python 3 installation....OK
      Version: 3.12.2
      Path: /Users/charlottewickham/.pyenv/versions/3.12.2/bin/python3
      Jupyter: 5.9.1
      Kernels: python3

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

[✓] Checking Julia installation...

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 in src/command/render/pandoc.ts at the template-partials validation, then read the referenced HTML and revealjs format files and the revealjs template. Run the two provided HTML and revealjs reproductions. Done means unsupported names are reported individually and revealjs reports only partials its template uses.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.