= 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 https://fontawesome.com/v4/get-started/[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:

[,html]
----
<link rel="stylesheet" href="css/font-awesome.css">
----

WARNING: The Font Awesome stylesheet assumes the fonts are located in a directory named [.path]_fonts_ adjacent to the directory containing the stylesheet (i.e., [.path]_../fonts_).
Therefore, if you don't set the `stylesdir` attribute, and you move [.path]_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 [.path]_font-awesome.css_ and adjust the path to the fonts (e.g., change the prefix to [.path]_fonts_ instead of [.path]_../fonts_).

If you rename the Font Awesome stylesheet to something other than [.path]_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.

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