Use Local Font Awesome

When font-based icons are enabled, the HTML converter configures the HTML document to retrieve the Font Awesome assets (CSS and fonts) from a CDN. This default behavior provides a convenience for users who want the visual enhancement of font-based icons without having to do any extra steps. There are valid concerns with linking directly to a CDN, especially one that’s outside your organization. Asciidoctor provides a way to point to a local copy of Font Awesome instead.

In this guide, we’ll assume that you’ve already enabled font-based icons on your document (i.e., set the icons attribute in your document to the value font).

Prepare the Font Awesome assets

The first thing you’ll need to do is download a copy of Font Awesome. The HTML converter currently integrates with Font Awesome 4, so make sure you’re using that version.

Extract the zip file and arrange the Font Awesome assets into the location of the output file (i.e., the HTML file generated by Asciidoctor) as follows:

css/font-awesome.css
fonts/fontawesome-webfont.eot
fonts/fontawesome-webfont.svg
fonts/fontawesome-webfont.ttf
fonts/fontawesome-webfont.woff
fonts/fontawesome-webfont.woff2

It’s important that these files are located in the same directory as the output file. If that’s the same directory where the AsciiDoc file is located, then you’re already set.

Switch to your local Font Awesome assets

Now that you’ve set up Font Awesome locally, you’ll need to instruct Asciidoctor to use it instead of the one from the CDN. The key attribute that controls this behavior is iconfont-remote. But default, this attribute is set. If you unset this attribute (e.g., -a iconfont-remote!), Asciidoctor will look for the Font Awesome stylesheet in the stylesdir. We’ll assume that you’re setting the stylesdir attribute to the value css. If you have a custom stylesheet, it should be located in that folder as well.

Here’s what the call looks like with these attributes configured:

$ asciidoctor -a stylesdir=css -a iconfont-remote! doc.adoc

This will configure the HTML to reference Font Awesome as follows:

<link rel="stylesheet" href="css/font-awesome.css">
The Font Awesome stylesheet assumes the fonts are located in a directory named fonts adjacent to the directory containing the stylesheet (i.e., ../fonts). Therefore, if you don’t set the stylesdir attribute, and you move font-awesome.css to the directory containing the output file, the Font Awesome stylesheet will look in the wrong location for the fonts and the icons won’t work. To fix the problem, you can edit font-awesome.css and adjust the path to the fonts (e.g., change the prefix to fonts instead of ../fonts).

If you rename the Font Awesome stylesheet to something other than font-awesome.css, you can tell the HTML converter which basename to use by setting the iconfont-name attribute. Let’s assume that you have set up your Font Awesome assets as follows:

css/fa.css
fonts/fontawesome-webfont.eot
fonts/fontawesome-webfont.svg
fonts/fontawesome-webfont.ttf
fonts/fontawesome-webfont.woff
fonts/fontawesome-webfont.woff2

You then pass the modified basename of the stylesheet using the following call:

$ asciidoctor -a stylesdir=css -a iconfont-remote! -a iconfont-name=fa doc.adoc

If you want to change the name of the fonts directory, or you want to configure the Font Awesome stylesheet to only attempt to load one of the fonts, you’ll need to modify the stylesheet directly.

You can use these same attributes to integrate a different icon font library, though it must work in the same way as Font Awesome.