7.11 Add a custom browser icon

Section 7.10 demonstrates that we can inject additional code into the HTML head, body, or footer with the includes option of the html_document format. This technique can be used to add a custom browser icon, called a favicon, to your HTML output.

Favicons are the website logos that are displayed in your browser’s address bar, tab title, history, and bookmarks. For example, if you visit the CRAN website (https://cran.r-project.org) in Google Chrome, and look at the browser tab, you will see a small R logo. On mobile devices, favicons are also used in place of an App icon for websites that are pinned to the home screen.

To add a favicon to your HTML document, add the following line of code to a custom header file (such as the file header.html mentioned in Section 7.10):

<link rel="shortcut icon" href="{path to favicon file}" />

Recall that this file can be injected into the document <head> area using the YAML metadata:

output:
  html_document:
    includes:
      in_header: header.html

The path you provide to the href attribute in <link> should assume the same relative path structure as you would use to reference any other asset (e.g., an image or dataset). For the image itself, most small, square PNG files will work reasonably well. Bear in mind that a typical web browser will often display the image in a 16 x 16 pixel box, so simple designs are better.

If you want to ensure that each browser or platform on which your document is viewed uses a version of your icon with optimal resolution for its specific layout, you may use a service such as https://realfavicongenerator.net to generate a set of favicons and a slightly more complex version of the header HTML code. This service is currently used by the pkgdown package’s pkgdown::build_favicon() function (Wickham, Hesselberth, and Salmon 2022) to make a set of favicons out of R package logos.

References

Wickham, Hadley, Jay Hesselberth, and Maëlle Salmon. 2022. Pkgdown: Make Static HTML Documentation for a Package. https://pkgdown.r-lib.org.