Add a Favicon

When using Asciidoctor to generate a standalone HTML document (i.e., the standalone option is true), you can instruct the processor to include a link to a favicon by setting the favicon attribute in the document header.

= Document Title
:favicon:

By default, the processor will add a link reference of type "icon" that refers to a file named favicon.ico (relative to the HTML document):

<link rel="icon" type="image/x-icon" href="favicon.ico">

This reference gets added inside the HTML <head> element (which explains why this feature is not available when generating an embeddable HTML document).

To modify the name or location of the icon file, simply assign a value to the favicon attribute:

= Document Title
:favicon: ./images/favicon/favicon.png

This will now produce the following HTML element:

<link rel="icon" type="image/png" href="./images/favicon/favicon.png">

Notice the mimetype is automatically set based on the file extension of the image.

The value of the iconsdir attribute is not prepended to the favicon path as it is with icons in the content. If you want this directory to be included in the favicon path, you must reference it explicitly:

:favicon: {iconsdir}/favicon.png

If you’re converting a set of AsciiDoc files in multiple directories for the purpose of making a website, and the favicon is located in a shared location, you’ll likely want to use a forward slash (/) at the beginning of the favicon path.

If you’re looking for more control over how the favicon is declared, you should use a head docinfo file. Keep in mind that if you add an icon link in a head docinfo file and also set the favicon attribute, you’ll end up with two icon links in the generated HTML document.