Setting open-graph and twitter images for all chapters of a Quarto book

[ferenci-tamas]

Description

I was under the impression that if I set image in _quarto.yml (and set open-graph and twitter-card to true) than that image will be used for all chapters in a Quarto book (where chapters are in different HTML files). This seems to be logical, as one would probably want to see the same sharing image no matter what concrete chapter is shared from the same book.

However, it seems to me that

• In the first chapter (i.e., index.qmd) the cover-image is used as og:image and twitter:image (instead of the image),
• In any subsequent chapter, if the chapter includes at least one image, the first image is used as og:image and twitter:image (instead of the image),
• And image is only used as og:image and twitter:image if the chapter is not the first one and it does not contain a single image.

Isn't it a bug...? Especially because the documentation says "by default, Quarto will use the image value from the format metadata", and this is exactly what I have done, provided an image value in the format metadata -- yet, Quarto will use different image (probably in all cases, if we do not have chapters without image!).

A minimal reproducible example:

_quarto.yml:

project:
  type: book

book:
  title: "Quarto book"
  cover-image: cover.png
  image: ogimage.jpg
  open-graph: true
  twitter-card: true
  chapters:
    - index.qmd
    - chap1.qmd

format:
  html:
    theme: cosmo

index.qmd:

# Preface

Preface

chap1.qmd:

# Chapter 1

![Chapter 1 image](chap1.png)

Now, if you render this, the main page's HTML will include <meta property="og:image" content="cover.png"> (and similarly for twitter:image) while Chapter 1's HTML will include <meta property="og:image" content="chap1.png"> (and similarly for twitter:image). I.e., the image I have set above, ogimage.jpg does not even appear...!

[mcanouil]

Your quote is partial:

The path to a preview image for this content. By default, Quarto will use the image value from the document metadata, or if that isn’t specified, the image value from the website: metadata. If you provide an image, you may also optionally provide an image-width and image-height to improve the appearance of your Twitter Card.

If image is not provided, Quarto will automatically attempt to locate a preview image. For more information, see Preview Images.

Source: https://quarto.org/docs/websites/website-tools.html#social-metadata

Unfortunately as you did not provide a small reproducible example for example using quarto create project book, it's very hard to know if there is a bug, a documentation issue or a misused configuration.

[ferenci-tamas]

If you think @mcanouil that this is a bug, I happily post it under issues, if that is more appropriate! (Now this seems to be a bug to me, but originally I was somewhat unsure, that's why I decided to post it as a discussion.)

[mcanouil]

Let the team check and investigate.
We can "convert" to an issue at any point ourselves.

[ferenci-tamas]

Ah, I didn't know that! Great, and thank you very much!

[mcanouil]

FYI, there is a GitHub feature for this purpose in the right sidebar:

[ferenci-tamas]

I have never even noticed it... thank you!

[ferenci-tamas]

Dear @mcanouil , I discovered something, and I thought it worth sharing here. Namely, I realized that if I move the image: ogimage.jpg line from the book part to the format:html part in the _quarto.yml, everything seems to be working immediately perfectly...! (I.e., ogimage.jpg will be the sharing image for every chapter.) I'd appreciate a confirmation of this, as this was only a chance finding on my part, but it seems to work.

I first thought that this was a very trivial mistake on my part, surely I just haven't read the documentation carefully enough. Now, with this knowledge in my mind, I returned to the manual, and I think it is not really clear: image appears both under the Reference / Formats / HTML part and the Reference / Projects / Book part section, which would suggest to me that both can be used, which is, as we have seen, not the case, as the two gives different results. (As a comparison, open-graph only appears in the Book part, so it is clear where should it be placed.) Also, for the image, the Formats / HTML says by default, Quarto will use the image value from the site: metadata, while Book says by default, Quarto will use the image value from the format metadata which is simply circular, isn't it...? (Even if we disregard the problem that the first is not true, and if image is missing under format:html then the one under book will not be used.)

So after all, isn't it just a minor problem with the documentation...?

[mcanouil]

Could you create an actual reproducible example that does not involve to have to find images, etc.?
Like a GitHub repository with at least quarto create project book.
Note that there is a shortcode to include placeholder images: https://quarto.org/docs/authoring/placeholder.html
The shortcode takes images from https://placehold.co/

Thanks

[mcanouil]

I did make a usable working example:

https://github.com/mcanouil/quarto-issues-experiments/tree/main/quarto-cli-11914

---

I don't think image is actually used in Books when using cover-image.
The reference schema is reusing the components/documentation thus the inaccuracy (maybe worth adding a bit more about cover-image in the schema and https://quarto.org/docs/books/book-output.html#cover-images).
For books image should be read as cover-image (if used) inside twitter/open-graph.
The precedence is open-graph.image > cover-image > image.

When you use image under format, it works because of the order in which the metadata are used/merged.

If you want to use a social image that is not the cover, then you need to be explicit about it:

  cover-image: cover.png
  twitter-card:
    image: social.png
  open-graph:
    image: social.png

For short, in Books, you can't use image and cover-image at the project level as cover-image takes precedence over image.

[ferenci-tamas]

Thank you very much, this solution is working perfectly! (Although the documentation could be perhaps a bit more clear about this whole question.)