Banner Graphic

←BLOG INDEX || Home || View/Save as PDF

Fabulous Favicons

by Tom Swan

Favorites Icons (favicons for short) — those little pictures next to filenames, browser tabs and bookmarks — may be small but their importance to software interfacing is anything but trivial. I open many files and select countless bookmarks by favicon images alone, barely glancing at the associated titles. Many of you probably do the same.

In this article I explain the proper and not-so-proper ways to attach favicon images to Asciidoctor-generated HTML documents. We will examine:

  • recommended favicon HTML tags and settings

  • a quick and dirty way to attach favicons to documents

  • a better method that leaves the resulting HTML fresh and clean

The ZIP file that accompanies this article demonstrates two ways to attach favicons to AsciiDoc documents. Unpack the ZIP file ( to create subfolder fav. In that folder, open index.html to view the demonstration in a web browser. Select between the two links to run the tests, and look for the favicon image in your browser’s tabs and bookmarks.

Here’s the ZIP file DOWNLOAD link and a TRY-IT-NOW link:

TRY-IT-NOW (to read along, open in new tab or window)

Favicon Demonstration (LIVE)

Favicon Images

Like pictures, favicons are worth a thousand words (or more!). They come in all sizes and formats, from old-time 16x16-pixel bitmaps to GIF, JPEG, and PNG formats in various sizes and in all the colors of the rainbow. Image sizes of 72x72 seem to be the norm in a lot of web sites today. 32x32 also works.

For this demonstration, I’ll use a PNG image. A search online for public domain images easily located an appropriate candidate shown in Figure 1 (click image to expand).

Figure 1. doodle-sun-2.[1]
You can find all image files mentioned here in the unpacked ZIP file’s image subfolder.

Figure 2 shows the test favicon after I reduced the high-resolution image down to a more icon-compatible 72x72-pixels square (I also added a green mask to improve the tiny image’s visibility):

Figure 2. favicon-72x72.png

If you have the Gimp graphics editor, you can also open my graphics work file to which I added a green mask-border after scaling the original:

Favicons and AsciiDoc

To use a PNG image for a favicon, most sources I consulted suggest inserting the following tag into the HTML document’s <head>:

<link rel="icon" type="image/png" href="image/favicon-72x72.png">
  • rel — relationship of this <link> to the document

  • type — graphics file format

  • href — URL to the favicon image file

Inserting Favicons: The Not So Right Way

Let’s get the wrong way out of the way. First store your favicon image where you can find it. Ours is in folder image. Next, insert the following lines near the top of your AsciiDoc text:

  <link rel="icon"

The two lines of four plus signs are AsciiDoc’s "pass-through" command. The text in between is injected directly into the HTML output, in this case inserting a <link> tag with the properties shown. This can also be in the form http://<path>/<file>.png.

The problem with this method is that it injects the HTML tag into the <body> of the document. It is more proper to place such statements in the <head> element as I explain next.

Inserting Favicons: The Right Way

The right way to attach a favicon to an AsciiDoc document is also useful for inserting other HTML tags that you want in the <head> element. First, create a file named docinfo.html with the following lines:

<!-- docinfo.html -->
<link rel="icon"

That’s the same <link> element from before but with a comment on top to identify the filename.

For a quick test, open docinfo.html in a browser and it should display the favicon in tabs and bookmarks.

Next, in your AsciiDoc text, set docinfo to shared with the declaration:

:docinfo: shared

Compiling the text with Asciidoctor copies the docinfo.html file’s contents into the generated <head> element. The favicon should now appear in the browser when you open the generated file.

Other Uses for docinfo Files

You can put anything you want in the docinfo.html file and it will be inserted into the HTML <head> (replace xxxxx below with a real file name):

<link rel="stylesheet" href="css/normalize.css">
<script src="xxxxx.js"></script>

That inserts a stylesheet link and a hypothetical Javascript file reference into the HTML <head> section.


From a terminal prompt, go into the demonstration fav folder and type make to compile all files. Of course, you must have Asciidoctor installed. Type make clean to erase generated files.
For other docinfo uses and for more information about docinfo files in general, browse to this Asciidoctor User Manual Link.
Just for fun, try counting all the icons you can see on your favorite computing device. I did that just now and came up with 62. In a world of ever decreasing attention spans, that’s a lot of symbolic power looking to attract a potential reader’s eye! Something, perhaps, for self-publishing writers to think about.

1. source: