Support for covers images in listings of Jupyter notebooks

[alyst]

Description

Before submitting an issue, I just wanted to check here, whether the cover images are supported for Jupyter python notebooks.
It is working for me with R notebooks (knitr engine + ggplot), but in Jupyter notebooks the figure with labels starting with cover_ are not picked up as covers.
In fact, none of the plots are picked up as covers, although I see that the cover_...-output-1.png files are generated.
Also, the class: preview-image attribute does not seem to have any effect in Jupyter notebooks, I don't see preview-image in the classes of the generated div/img elements in the html output.
Am I doing something wrong?

[mcanouil]

Could you share a small self-contained "working" (reproducible) example to work with, i.e., a complete Quarto document or a Git repository? The goal is to make it as easy as possible for us to recreate your problem so that we can fix it: please help us help you! Thanks.

---

You can share a self-contained "working" (reproducible) Quarto document using the following syntax, i.e., using more backticks than you have in your document (usually four ````).
See https://quarto.org/bug-reports.html#small-is-beautiful-aim-for-a-single-document-with-10-lines.

If you have multiple files (and if it is absolutely required to have multiple files), please share as a Git repository.

R	Python
````qmd --- title: "Reproducible Quarto Document" format: html engine: knitr --- This is a reproducible Quarto document. {{< lipsum 1 >}} ```{r} x <- c(1, 2, 3, 4, 5) y <- c(1, 4, 9, 16, 25) plot(x, y) ``` {#fig-placeholder} {{< lipsum 1 >}} The end after @fig-placeholder. ````	````qmd --- title: "Reproducible Quarto Document" format: html engine: jupyter --- This is a reproducible Quarto document. {{< lipsum 1 >}} ```{python} import matplotlib.pyplot as plt x = [1, 2, 3, 4, 5] y = [1, 4, 9, 16, 25] plt.plot(x, y) plt.show() ``` {#fig-placeholder} {{< lipsum 1 >}} The end after @fig-placeholder. ````

Additionally and if not already given, please share the output of quarto check within a code block (i.e., using three backticks ```txt), see https://quarto.org/bug-reports.html#check.

[alyst]

@mcanouil Sure, I can do it, but that was the purpose of my question -- to check whether the cover image logic is supposed to work for Jupyter notebooks and whether there are any Quarto projects that use this feature.
If it is supposed to work, but nobody has tested it so far, I can create a MRE project.

[mcanouil]

Quarto supports ipynb and qmd. Unless stated, everything should work for both.
Now without any example there is no way to tell if it does or not.

Am I doing something wrong?

I was "replying" to your question.
You asked for something without providing anything concrete to work on. I have no idea what and how you did something that you claim did not work.

[alyst]

Ok, I've created the MRE, I can share it, but I have found out that the issue is related to self-contained: true set for html format.
Are the cover images suppose to work with self-contained HTML output? If not, maybe it has to be clarified in the manual.

The issue with class: preview-image having no effect for the Jupyter notebook is still there, though
For knitr-generated html files the outer div that encompasses the source and the output has it in the class attribute, but not for Jupyter.

[mcanouil]

Short answer: No.

self-contained is a three years old deprecated option. Use embed-resources as documented.
This option is for single document not projects like books or website.

• Disallow embed-resources for Book and Website project ? #11316

[alyst]

I can confirm that listing cover images logic does not work for notebooks with embed-resources: true.
@mcanouil Thanks for your help.

[mcanouil]

What do you expect embed-resources to do in a website?
If the images are base64 encoded inside the document, how do you expect other pages of the website to access them?

Note that, I'm pretty sure it does not work at all and not only for Jupyter Notebooks.

There is really no reason to use embed-resources in a book or website project as the purpose of those is to share components across pages while embedding resources is the exact opposite goal.
At best (if/when working in those contexts), you get a overall project's that explodes because you duplicated every single shared resources (css, JavaScript, logo, etc.) across all pages.

[alyst]

I don't expect arbitrary referencing of images across the pages with embedded resources to work (I assumed embedding happens at the level of individual pages). But thumbnails are a bit different story -- there is only one thumbnail per notebook, and which image should be used for a thumbnail is defined at the time of its rendering, not when it is referenced.

[mcanouil]

There are no "thumbnail". It's the actual cover image that is used as you can see when inspecting the listing page, but still embed-resources is not only for images, it's for "resources", that is everything used by the pages.

[alyst]

there are no "thumbnails"

If by "thumbnail" you mean "reduced scale image specifically generated for the listings" (with the emphasis on reduced scale and specifically generated), I agree.
But I think it is still true that one can identify the image that might be referenced for the listings from the other pages at the time of this page rendering.
For that reason, theoretically it could be possible to make an exception from embed-resources logic and, in addition to embedding it, generate a standalone thumbnail.

but still embed-resources is not only for images, it's for "resources", that is everything used by the pages

Which is a nice feature that allows treating certain website pages (since embed-resources could be specified at the page/folder level) as standalone documents, which could be downloaded.

To be clear, I do not propose implementing listings support for embed-resources pages.
I am just saying that embed-resources option for website format is not totally useless and even can be made to work with listings.

The only thing I suggest is that it would be nice if Quarto can warn the user about the limitations that embed-resources imposes for websites.

[mcanouil]

The option is a Pandoc option with little changes from Quarto.
And note the issue about this option in the context of multi-pages project.

I think you would be better served to create a custom HTML format that uses the embed resources option alongside the "format linking" feature which will actually makes the page downloadable.
This would at least not breaks a lot of other website/books features.

[cderv]

I am not sure if I have encompassed all the nature of the issue here. However, I noticed we are talking about embedded resources and maybe avoiding embedding some of the content.

I just want to share that adding data-external="1" as attributes to any content will avoid the embedding of this specific contact.

Sharing in case it can help. Sorry if I am out of context

[mcanouil]

I am not sure if I have encompassed all the nature of the issue here. However, I noticed we are talking about embedded resources and maybe avoiding embedding some of the content.

TL;DR: Automatic preview images detection for listings (website project) did not work when using embed-resources: true.
Another case in favour of:

• Disallow embed-resources for Book and Website project ? #11316

I just want to share that adding data-external="1" as attributes to any content will avoid the embedding of this specific contact.

Thanks, I always forgot about this.