resolves #4044 document how to use a local copy of Font Awesome

document the iconfont-remote and iconfont-name attributes

1 files changed, 71 insertions, 0 deletions

diff --git a/docs/modules/html-backend/pages/local-font-awesome.adoc b/docs/modules/html-backend/pages/local-font-awesome.adoc
new file mode 100644
index 00000000..a975757b
--- /dev/null
+++ b/docs/modules/html-backend/pages/local-font-awesome.adoc
@@ -0,0 +1,71 @@
+= 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.