Hinode Module - Font Awesome

A Hugo module to add Font Awesome icons to your Hinode site

About

Hinode is a clean blog theme for Hugo, an open-source static site generator. Hinode is available as a template, and a main theme. This repository maintains a Hugo module to add Font Awesome icons to a Hinode site. Visit the Hinode documentation site for installation instructions.

Installation

This module is imported automatically when using Hinode. To use it in your own Hugo site:

1. Add the module to your hugo.toml:

   [module]
     [[module.imports]]
       path = "github.com/gethinode/mod-fontawesome/v5"

2. Vendor the module (optional but recommended):

   hugo mod vendor

3. Use icons in your templates or content:

   {{- partial "assets/icon.html" (dict "icon" "fas fa-heart") -}}
   

No npm installation required - all Font Awesome assets are automatically included via Hugo modules.

Configuration

Important

Font Awesome v7 requires Dart Sass to function correctly. It no longer supports LibSass. See the Hugo Docs for installation instructions.

This module supports the following parameters (see the section params.modules in config.toml):

Setting	Default	Description
fontawesome.mode	"symbols"	Icon rendering mode: "symbols" (static SVG sprites with <use> references), "svg" (inline SVG elements), or "webfonts" (CSS webfonts). Symbols mode offers the best performance.
fontawesome.defaultFamily	"fas"	Default icon family for shorthand notation (e.g., {{< icon "user" >}} uses this family).
fontawesome.debug	false	If set, prints debug information to Hugo build output.
fontawesome.skipMissing	false	If set, displays a warning when an icon cannot be found instead of exiting with an error.

Example configuration:

[params.modules.fontawesome]
  mode = "symbols"      # Use SVG symbols (recommended)
  defaultFamily = "fas" # Default to Font Awesome Solid
  debug = false
  skipMissing = false

Notes

Hugo Module Architecture

This module imports the official Font Awesome repository directly as a Hugo module, eliminating the need for npm dependencies. Font Awesome assets (SVG files, SCSS, and webfonts) are vendored automatically by Hugo's module system.

Key features:

• No npm required: All Font Awesome assets come from the official Git repository
• SVG-first approach: Uses Font Awesome 7.x SVGs (svgs/) with overflow="visible" to prevent icon clipping
• Symbol map support: Generate reusable SVG symbols for optimal performance
• CI/CD compatible: Works identically in development and production environments

Version Management

Font Awesome changed its version tagging pattern after v4.x, breaking semantic versioning compatibility with Go modules (see issue #17342). As a workaround, this module imports the 7.x branch, which Go resolves to a pseudo-version in go.mod:

require (
  github.com/FortAwesome/Font-Awesome v0.0.0-20260210181720-337dd2045d56
)

To update to the latest Font Awesome 7.x release:

hugo mod get -u github.com/FortAwesome/Font-Awesome@7.x
hugo mod tidy
hugo mod vendor

Note: The @7.x branch reference is needed in the hugo mod get command because Font Awesome uses non-standard version tags (e.g., "Release 7.0.0" instead of "v7.0.0").

Contributing

This module uses semantic-release to automate the release of new versions. The package uses husky and commitlint to ensure commit messages adhere to the Conventional Commits specification. You can run npx git-cz from the terminal to help prepare the commit message.