Document what cover-image actually does

[hammer]

I've tried adding images/cover.png to my repo and cover-image: images/cover.png to the index.Rmd YAML header. When I build the book, nothing is included. Following the advice on the RStudio Discourse, I've added an R chunk to include this image only when building HTML output. Unfortunately, this just generates a broken image link. I was also surprised to learn that cover-image does nothing for PDF output. I searched for cover-image in this repo to see if I could find the code that handles this option but nothing turned up.

So, would you consider adding a bit more detail to the Bookdown book (or some other canonical source) on what the cover-image option actually does, and how to use it to insert and serve a cover image for an HTML book published someplace?

[yihui]

It is for EPUB only. Please see Pandoc's manual (as I often suggest): https://pandoc.org/MANUAL.html

Whenever you see a top-level field in YAML that you don't understand, the first thing to do is check Pandoc's documentation. If you cannot find it there, you may come back here to ask. Thanks!

[hammer]

In the bookdown book you refer to cover-image as one of the

top-level options in the YAML metadata that can be passed to the GitBook HTML template via Pandoc

When used as a top level option in the Pandoc manual, this option is named epub-cover-image. Why not use this more descriptive name in knitr?

Further, you state that

A nice effect of setting description and cover-image is that when you share the link of your book on some social network websites such as Twitter, the link can be automatically expanded to a card with the cover image and description of the book.

So it seems cover-image does have some impact on HTML outputs, not just EPUB outputs? Or no?

[yihui]

It is named cover-image: https://pandoc.org/MANUAL.html#epub-metadata Pandoc's manual doesn't contain a top-level YAML option named epub-cover-image. There is only a command-line argument named --epub-cover-image.

For your second question, the answer is yes.

[github-actions]

This old thread has been automatically locked. If you think you have found something related to this, please open a new issue by following the issue guide (https://yihui.org/issue/), and link to this old issue if necessary.