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
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.
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
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
We’ll assume that you’re setting the
stylesdir attribute to the value
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
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.