Notebook previews don't pick up options from a custom format extension

[mcanouil]

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 page embeds a notebook cell with {{< embed >}}, Quarto also builds a preview page for that notebook.
I noticed that if the project uses a custom format from an extension, the preview doesn't get that format's options.
The host page and the notebook's own page get them just fine.
With the built-in html format, the preview gets the same options as the other pages, which is what I'd expect.

I'm not completely sure this isn't intended, but it does feel like a bug.

I think it comes from renderHtmlNotebook in src/render/notebook/notebook-contributor-html.ts.
It renders the preview with formats: ["html"] and only carries over the host format's theme, so the rest of a custom format's options are left behind.

I ran into this while moving the quarto.org theme into a local extension.
The notebook previews there lost the header and footer scripts that the site's format adds.

Steps to reproduce

Here's a small project with four files, and none of them need a computation engine.

_quarto.yml:

project:
  type: default

format: myformat-html

_extensions/myformat/_extension.yml:

title: My Format
author: Example
version: 1.0.0
contributes:
  formats:
    html:
      include-in-header:
        text: '<meta name="from-myformat" content="yes">'

index.qmd:

---
title: "Host page"
---

{{< embed notebook.ipynb#cell-hello >}}

notebook.ipynb:

{
 "cells": [
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "---\n",
    "title: Notebook\n",
    "---"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "c1",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello\n"
     ]
    }
   ],
   "source": [
    "#| label: cell-hello\n",
    "print(\"hello\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}

Then render it and look for the tag in each page:

quarto render
grep -c 'from-myformat' index.html notebook.html notebook-preview.html

Actual behavior

The tag from the custom format is missing from the preview:

index.html:1
notebook.html:1
notebook-preview.html:0

Expected behavior

I'd expect the preview to get the custom format's options, like the other two pages:

index.html:1
notebook.html:1
notebook-preview.html:1

That's exactly what happens with the built-in format.
If you swap format: myformat-html in _quarto.yml for the following, all three pages have the tag:

format:
  html:
    include-in-header:
      text: '<meta name="from-myformat" content="yes">'

Your environment

• IDE: none, I ran quarto render from the terminal.
• OS: macOS 27.0.
• I also reproduced it with a development build of quarto-cli at 5757cfc88.

Quarto check output

Quarto 1.10.18

[✓] Checking environment information...
      Quarto cache location: /Users/mcanouil/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: ~/quarto-1.10.18/bin

[✓] Checking tools....................OK
      TinyTeX: v2026.07
      Chrome Headless Shell: (not installed)
      VeraPDF: (not installed)

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

[✓] Checking Chrome Headless....................OK
      Using: Chrome from QUARTO_CHROMIUM
      Path: /Applications/Brave Browser.app/Contents/MacOS/Brave Browser

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

ℹ R version 4.6.1 (2026-06-24)
! Config '~/.Rprofile' was loaded!

[✓] Checking R installation...........OK
      Version: 4.6.1
      Path: /Library/Frameworks/R.framework/Versions/4.6/Resources
      LibPaths:
        - /Users/mcanouil/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.9.6
      Path: /Library/Developer/CommandLineTools/usr/bin/python3
      Jupyter: (None)

      Jupyter is not available in this Python installation.
      Install with python3 -m pip install jupyter

[✓] Checking Julia installation...

[cderv]

Thanks for the report. I can reproduce the 1/1/0 result. This is a real inconsistency with the built-in html format, and explains why moving the site theme into an extension removes the preview's header and footer scripts.

The preview currently asks for formats: ["html"]. Format resolution matches that list against the project's format keys by name. myformat-html is dropped, while a project keyed as html keeps its options:

quarto-cli/src/render/notebook/notebook-contributor-html.ts

Lines 155 to 157 in 39c153e

	const rendered = await renderFile(
	{ path: nbPath, formats: ["html"] },
	{

quarto-cli/src/command/render/render-contexts.ts

Lines 445 to 457 in 39c153e

	// If the file itself has specified permissible
	// formats, filter the list of formats to only
	// include those formats
	if (file.formats) {
	formats = formats.filter((format) => {
	return file.formats?.includes(format);
	});
	// Remove any 'to' information that will force the
	// rendering to a particular format
	options = safeCloneDeep(options);
	delete options.flags?.to;
	}

I have a candidate change that uses the host format when it is based on an HTML document. Your reproduction then gives 1/1/1. We still need the plain HTML format for a notebook embedded in a dashboard, since its preview is an HTML document rather than another dashboard.

There is one more interaction to resolve before calling this complete. The preview cache keeps one HTML preview per notebook path, but with this change the preview can depend on the host format. If pages with different formats embed the same notebook, the second page may reuse the first page's preview. An existing preview can also stay stale after the extension options change because cache revival compares the preview only with the notebook source. A notebook that declares its own format needs a separate check as well. I'm working through these cases before opening the PR.

However, this makes me think that it was design this way from the start, where notebook preview is a format on its own. So I want to think a bit more if this is the right change. It could be breaking change in a way. I want to braistorm about the possible edge case.

I'll re-label this to enhancement, because not sure this is bug, and rather an evolution of this feature.

[cderv]

One detail behind my hesitation: html-preview is an internal notebook render type with a fixed preview filename, its own template, and preview-specific settings. It is still rendered through HTML and copies selected host values, such as the theme. This suggests a distinct preview artifact, but it does not tell us that every option from the host's extension format should apply to it. I want to settle that behavior, including whether one notebook can have different previews for different host formats, before opening the PR.

[mcanouil]

I agree, that's also why I wasn't sure on which direction the issue was.
The more obvious element was that in the website, current behaviour with "html" leads to have the "posit badge" on the preview which is arguably correct in the context of a website as it allows to keep the chrome intact. Then switching to extension lead to this badge to not be there, which means inconsistent in that context.

So, should the html-preview be really independent or not? Should preview be fully integrated when in website? might be the real questions here, i.e., in manuscript project or single document project that is not really an issue to have the preview being its own format.
it matters mostly when sitting in a website.