Font Awesome DOCX sets the font of Font Awesome Icons in DOCX

[![GitHub build status][CI badge]][CI workflow]

Font Awesome DOCX is a Lua filter used to set the font of Font Awesome icons in Microsoft Word documents generated by Pandoc.

If the font for your Microsoft Word document does not support Font Awesome icons, you will end up with blank squares or a random character instead of the icon you intended.

This filter automates the setting of the font instead of having to manually post process the document after Pandoc generation

N.B: This filter is only relevant for Microsoft Word documents and does not support other document formats.

Prerequisites

Before using this filter you would need to complete the following steps:

1. Download the Font Awesome Desktop fonts from Font Awesome Download and install them on your computer.

2. Then create a DOCX reference document by using the following command:

   pandoc -o custom-reference.docx --print-default-data-file reference.docx

3. Next open the custom-reference.docx file in Microsoft Word and double click on the Styles Panel as annotated in the screenshot below:

   

The steps below guide you on how to create a New Style for the Font Awesome Regular Icons. You will need to repeat these steps for the Font Awesome Solid and Font Awesome Brands icons.

N.B. Ensure that the Font Awesome Solid style is named FontAwesomeSolid, and the Font Awesome Brands style is named FontAwesomeBrands so that the filter functions correctly.

1. Click on the New Style button. The steps below guide you on how to create a Style for the

   

2. In the Create New Style dialog set the name of the style to FontAwesomeRegular.

   N.B. If you name the style something else the filter will not function correctly.

3. Ensure that the Style type field is set to Character.

4. Ensure that the Style based on field is set to Default Paragraph Font.

5. Then choose the font for the Font Awesome regular icons by choosing the appropriate font and click OK.

   For the free version of Font Awesome the font name for the regular icons would be similar to Font Awesome 6 Free Regular.

   The annotated figure below shows all the settings described above:

   

   The color of the icon matches the font color of the text in the Word document.

   You may optionally choose a color to change the icon's appearance but this will change the color for all Font Awesome regular icons.

6. Next add the text FontAwesomeRegular to the end of the custom-reference.docx reference document.

7. Then, highlight the text you added above and scroll down the Styles Pane until you find the FontAwesomeRegular style. Then click on it to set the text to that style.

   

8. Finally, save the custom-reference.docx reference document.

Basic Usage

The Lua filter sets the font for Font Awesome icons by looking for a custom style that is appended to the Font Awesome icons in your Markdown source document.

For example if you using the regular icon like so in your Markdown source you should modify it to []{.fa-regular}.

For solid solid icons like you will need to change it to look like []{.fa-solid}.

For brands icons like the github icon you should change it to something like []{.fa-brands}.

Once you have made the above changes in your markdown run the following command:

pandoc -f markdown -t docx \
--reference-doc custom-reference.docx \
--lua-filter handle-font-awesome-docx.lua -o output.docx input.md

You should now see the Font Awesome icons showing up in the resulting Word document.

License

This pandoc Lua filter is published under the MIT license, see file LICENSE for details.