License Text: Please Read

Fabulous Favicons in AsciiDoc

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.

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).

You can find all image files mentioned here in the repository’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):


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.

1. source: