Font Awesome in Hugo

Here is a simple way to use Font Awesome in Hugo, the popular open-source static site generator.

Go to Font Awesome’s GitHub page and grab the newest release .zip file (fontawesome-free-X.Y.Z.zip).

In this ZIP file go to the folder fontawesome-free-X.Y.Z/svg-with-js/js/. Here is the file fontawesome-all.js, put this in your project’s static folder.

Now we will add a custom shortcode to hugo to make using Font Awesome easier: Create a folder shortcodes in your project’s layout folder if it does not already exist. Then create a new file with the name fa.html. The content of the file should be the following:

<!-- use default fontawesome class 'fas' or use a specified one like 'fab' for brands -->
{{ $faStylePrefix := "fas" }}
{{ if in (slice "fas" "far" "fal" "fad" "fab") (.Get 0) }}
  {{ $faStylePrefix = (.Get 0) }}
{{ end }}

<i class="{{ $faStylePrefix }} {{ range $iconName := .Params }} fa-{{ $iconName }} {{ end }}">
  <!-- Load font awesome only once per page, load it inside the <i> element
    so it does not disturb the text flow (like removing spaces) -->
  {{ if not (.Page.Scratch.Get "fontawesomeLoaded") }}
    {{ .Page.Scratch.Set "fontawesomeLoaded" true }}
    <link href="/fontawesome/css/all.min.css" rel="stylesheet">
  {{ end }}
</i>

Now you can use the {{< fa ICON_NAME >}} shortcode to inlcude Font Awesome icons in your markdown files. The ICON_NAME is the same as if you would use Font Awesome directly, but without the fa- prefix.

For example, use {{< fa bath >}} to have the icon of a bath in your text.

You can have modifiers like in regular Font Awesome too. E.g. 2x will double the size of the icon:
{{< fa bath 2x >}}    

To use some icons a style prefix has to be specified. For example to use brand icons the style prefix has to be fab. The style prefix has to be the first argument:
{{< fa fab github 2x >}}    

I’ve shown you a solution to easily add Font Awesome icons to your markdown text. A noticeable advantage of this approach is that no external dependencies (like https://use.fontawesome.com) are used.