Example of Using a Banner Image with RMarkdown

Purpose

The purpose of this document is to show how to create a banner image using RMarkdown

Background

A Reddit user asked, Is it possible to have a banner image with R-Markdown?. The short answer is “Yes.”

The longer answer requires understanding 1) how RMarkdown HTML document output incorporates CSS information and 2) web server permissions and file access.

In this example, I created a background image for the body of my HTML document by using the following custom CSS.

CSS Code Block

body {
  background-image: url('https://linesteppers.com/tutorials/RMarkdown/img/BannerImage_TreeBlossoms_4470x3024.jpg');
  background-repeat: no-repeat;
  background-size: 100%;
}

div {
  background-color: rgba(255, 255, 255, 0.35)   /* 35% opaque white */;
  padding: 0.25em;
}

I named this file CSSBackgrounds.css and placed it in the same directory as my .Rmd document. Then, I updated the YAML in my Rmd document as follows:

---
title: "Example of Using a Banner Image with RMarkdown"
author: "Thaufus"
date: "12/1/2019"
output: 
  html_document:
    css: CSSBackgrounds.css
---

Finally, the last key element to understand is why I used the following fully qualified path for my background image (see line #2 in my CSS Code Block above):

background-image: url('https://linesteppers.com/tutorials/RMarkdown/img/BannerImage_TreeBlossoms_4470x3024.jpg');

The reason I used this fully qualified path is because this image full is publicly accessible from any where. The mistake that most people make is to place the image they want in the same directory as their RMarkdown document, then to qualify access to it using a private file system path, such as this: file://CustomFileNameOnMyComputer.jpg.

By default, this approach will fail, and it should because of security reasons. Often, out of frustration, people will configure their server settings to grant access to such a file. Doing so opens a massive security hole.

The better approach is to place the image file in a location where their web server has default access, such as an image directory in the server’s root path, and then call the file from there.