HTML Partials docs do not describe the title block partials Quarto uses by default

HTML Partials セクションから始め、そこに記載されている pandoc/ partials と src/resources/formats/html/templates および format-html-title.ts#L133-L184 を比較します。title-block のバリエーション、それらの YAML セレクター、title-metadata.html への依存関係、および styles.html を文書化します。各設定に対して正しい開始 partial を読者が特定できれば完了です。

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):

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

1. State that title-block.html has variants in templates/, list them, and say which YAML options select each one (the table above).
2. 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.
3. 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").