License Text: Please Read
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.
This repository demonstrates the proper and not-so-proper ways to attach "favicon" images to Asciidoctor-generated HTML documents — the little icon pix next to filenames, browser tabs and bookmarks. Make sure they always appear when and where you want them by following the instructions layed out in these files.
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 source files in the GitHub-hosted repositories repository that accompanies this article demonstrate two ways to attach favicons to Asciidoctor documents.|
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 repository’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):
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