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 (
Here’s the ZIP file DOWNLOAD link and a TRY-IT-NOW link:
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).
You can find all image files mentioned here in the unpacked ZIP file’s
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):
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:
To use a PNG image for a favicon, most sources I consulted suggest inserting the following tag into the HTML document’s
<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
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" type="image/png" href="image/favicon-72x72.png"> ++++
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
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.
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" type="image/png" href="image/favicon-72x72.png">
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
shared with the declaration:
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.
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>
From a terminal prompt, go into the demonstration
|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.|