What the docs say
The HTML Partials section points readers at the pandoc/ resource directory and documents three replaceable partials: metadata.html, title-block.html, and toc.html.
What the code does
The title-block.html in that directory is not what a default format: html document renders. For every Bootstrap-themed document, Quarto injects a different set of title partials from templates/, selected by title-block-style and title-block-banner (format-html-title.ts#L133-L184):
| YAML |
Partial that renders |
default (or title-block-style: plain) |
templates/title-block.html |
title-block-banner set |
templates/banner/title-block.html |
title-block-style: manuscript |
templates/manuscript/title-block.html |
title-block-style: none |
pandoc/title-block.html |
templates/title-metadata.html and templates/_title-meta-author.html are always injected with them. Because staged partials resolve by basename, the injected templates/title-block.html replaces the documented pandoc/title-block.html in every default render — and a user partial named title-block.html replaces both.
Why this matters
A reader who follows the docs and copies pandoc/title-block.html as their starting point gets Pandoc's plain markup, not the markup Quarto renders. Their customization silently drops the quarto-title-block classes, so the theme's title styling and the title-block-banner options stop applying. In website projects it is worse: a postprocessor mangles any title block without those classes into two headers with duplicate ids — that rendering bug is tracked in #13841, which is also where this confusion was first reported. The correct starting point for customizing the default title block is templates/title-block.html (plus title-metadata.html, which it calls) — the docs never mention that these files exist.
Suggested additions to the HTML Partials section
- State that
title-block.html has variants in templates/, list them, and say which YAML options select each one (the table above).
- Point readers to
templates/title-block.html as the starting point for customizing the default title block, and note that it calls title-metadata.html, which can also be replaced.
- Document
styles.html, which is in the format's supported list and is referenced by both the HTML and Revealjs templates, but appears in neither format's documented partials.
An AI assistant helped investigate this issue, grounded in a local clone of quarto-cli (per CONTRIBUTING.md "Using AI tools to investigate").
What the docs say
The HTML Partials section points readers at the
pandoc/resource directory and documents three replaceable partials:metadata.html,title-block.html, andtoc.html.What the code does
The
title-block.htmlin that directory is not what a defaultformat: htmldocument renders. For every Bootstrap-themed document, Quarto injects a different set of title partials fromtemplates/, selected bytitle-block-styleandtitle-block-banner(format-html-title.ts#L133-L184):title-block-style: plain)templates/title-block.htmltitle-block-bannersettemplates/banner/title-block.htmltitle-block-style: manuscripttemplates/manuscript/title-block.htmltitle-block-style: nonepandoc/title-block.htmltemplates/title-metadata.htmlandtemplates/_title-meta-author.htmlare always injected with them. Because staged partials resolve by basename, the injectedtemplates/title-block.htmlreplaces the documentedpandoc/title-block.htmlin every default render — and a user partial namedtitle-block.htmlreplaces both.Why this matters
A reader who follows the docs and copies
pandoc/title-block.htmlas their starting point gets Pandoc's plain markup, not the markup Quarto renders. Their customization silently drops thequarto-title-blockclasses, so the theme's title styling and thetitle-block-banneroptions stop applying. In website projects it is worse: a postprocessor mangles any title block without those classes into two headers with duplicate ids — that rendering bug is tracked in #13841, which is also where this confusion was first reported. The correct starting point for customizing the default title block istemplates/title-block.html(plustitle-metadata.html, which it calls) — the docs never mention that these files exist.Suggested additions to the HTML Partials section
title-block.htmlhas variants intemplates/, list them, and say which YAML options select each one (the table above).templates/title-block.htmlas the starting point for customizing the default title block, and note that it callstitle-metadata.html, which can also be replaced.styles.html, which is in the format's supported list and is referenced by both the HTML and Revealjs templates, but appears in neither format's documented partials.An AI assistant helped investigate this issue, grounded in a local clone of quarto-cli (per CONTRIBUTING.md "Using AI tools to investigate").