Add an image to Rmarkdown Bookdown output before top level heading

Question

The example below (i.e. saved as a file index.rmd ) has the same code chunk to display an image above and below the top level heading, but the image doesn't appear above the top level heading. This occurs if there is a file _output.yml with only this entry bookdown::gitbook: in the same directory.

That line seems to enforce a table of contents (which I want) and that appears to strip out anything (image or text) before the first top level heading by default (which I don't want) - so can this behaviour be modified?

---
site: bookdown::bookdown_site
---

```{r echo=FALSE, message=FALSE, warning=FALSE}
library(imager)
im <- load.image(system.file('extdata/Leonardo_Birds.jpg',package='imager'))
plot(im, axes=FALSE)
```

# R Markdown

```{r echo=FALSE, message=FALSE, warning=FALSE}
library(imager)
im <- load.image(system.file('extdata/Leonardo_Birds.jpg',package='imager'))
plot(im, axes=FALSE)
```

Answer 1

What follows is workaround to your Options 2 and 3, using Markdown and CSS to style images and HTML+CSS to style text; also, using base64 image (transparent gif) generator as an space separator between elements.
Beware of whitespaces! (at the end of each line - place two white spaces and hit ENTER)
Does one of these approaches/hacks work for you? If not, it would be better to delete the answer, it may be misleading to others.

---
title: |
  ![](www/image.png){width=300px}|  
  |:-:|  
  ![](www/image.png){width=300px style="display: block; margin:0 auto"}  
  ![](www/image.png){width=300px height=90px align=left}  
  ![](www/image.png){width=300px height=90px align=center}  
  ![](www/image.png){width=300px height=90px align=right}  
  ![](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==){width=150px}  
  R Markdown Title  
  <center>R Markdown Title</center>  
  <p style="text-align: right;">R Markdown Title</p>   
  ![](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==){width=150px}
author: "Author Name"
date: "08/03/2020"
---

Using Markdown table to "style" images |-| (left-aligned), |:-:| (centered) and |-:| (right-aligned) will work well with simple RMarkdown outputs.

I realised that you have an image under # top level heading positioned at the very top of the page - with top:0px. causing image duplication and, possibly, hover problem:

<img src="https://i.imgur.com/GiViTbA.png" style="position:absolute;top:0px;height:100px;" />

replace with:

![](http://stackoverflow.com/favicon.ico){width=50px style="display: block; margin:0 auto;"}

and see what will happen.

---
title: |
  ![](https://i.imgur.com/GiViTbA.png){width=300px style="display: block; margin:0 auto;"}  
  ![](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==){width=50px}  
  R Markdown Title  
  ![](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==){width=50px}
output:
  html_document: default
---

# I'm a top level heading {-}

![](http://stackoverflow.com/favicon.ico){width=50px style="display: block; margin:0 auto;"}

Note, you need to replace the image with a local image if you want to show the image in the rstudio viewer.
The image will be visible in the html file created when you knit, if you open in a browser connected to the internet.

```{r echo=FALSE, message=FALSE, warning=FALSE}
plot(cars)
```

EDIT:

Let's try to find a common ground, A Minimal Book Example, github here.

Adjustments made in index.Rmd:

--- 
title: |
  ![](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==){height=300px}  
author: "Author Name"
date: "`r Sys.Date()`"
site: bookdown::bookdown_site
output: bookdown::gitbook
---

# Prerequisites

<img src="https://i.imgur.com/GiViTbA.png" style="position:absolute;top:50px;height:300px;align:center;" /> 

This is a _sample_ book written in **Markdown**. You can use anything that Pandoc's Markdown supports, e.g., a math equation $a^2 + b^2 = c^2$.

index.Rmd output:

Adjustments made in Chapter: Introduction (01-intro.Rmd):

# Introduction {#intro}

![](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==){height=240px}

<img src="https://i.imgur.com/GiViTbA.png" style="position:absolute;top:50px;height:300px;align:center;" />

You can label chapter and section titles using `{#label}` after them, e.g., we can reference Chapter \@ref(intro). If you do not manually label them, there will be automatic labels anyway, e.g., Chapter \@ref(methods).

01-intro.Rmd output:

With this solution we are "masking" a top level heading (# Introduction) with .png image, which will appear in the Table of Content as text.
Disadvantage: besides the obvious hack, image width must be at least equal or wider than top level heading title.

Answer 2

Note: 3 options are provided here, and none of them are perfect. The perfect solution may rely on modifications to the bookdown package?

Option 1:
Use includes with before_body like this in your _output.yml file (suggested here):

bookdown::gitbook:
  css: assets/style.css
  includes:
    before_body: assets/big-image.html
    after_body: assets/footer.html

Disadvantages:
i) Requires making a html file just to insert an image.
ii) If using a web-based image, won't show in Rstudio viewer.
iii) If using a local image, path can get mixed up and won't show in online web html rendering
iv) Includes image at the top of each chapter of bookdown if using before_body: my_image.html. Alternative option in_header: my_image.html does not seem compatible with the sidebar index.

Option 2
Insert image via yaml in index.rmd, using the solution under Tip 3 Add a Logo in your title/header/footer at this blog post

--- 
title: |
  ![](my_image.png)  
  My title

Disadvantages:
i) When you hover over the image, it displays a copy of the image in a slightly different location (Can this "Hover" behaviour be disabled?)
ii) If using a web-based image, won't show in Rstudio viewer.
iii) If using a local image, path can get mixed up and won't show in online web html rendering

Option 3
The code below borrowed from here (which you can place below the top level heading) presumably goes direct through the knitting process and inserts itself in the final html. The issue is that the image doesn't make room for itself and ends up over the first text. Is there some simple html/css to sort this out?

<img src="https://i.imgur.com/GiViTbA.png" style="position:absolute;top:0px;height:100px;" />   

Disadvantages:
i) Image doesn't make room for itself and ends up over the first text. You can get around this with a hack by coding extra space (trial and error) through the yaml title like this:

title: |
    .      

    .  

    .  

    .  

site: bookdown::bookdown_site