- SVG symbol icon system: High performance with great browser support
- Currently supports Font Awesome, but aims to be icon-family agnostic in future
- User-friendly API with support for various usage patterns, including custom icon name support
- Carefully implemented and structured partials
- Smart and comfortable icon search function
- Auto-enabled accessibility by considering icon’s metadata
Initialize Hugo's mod system on your site:
hugo mod init github.com/<username>/<your-repo>
Add module to site's config (e.g. config.yaml):
module:
imports:
- path: github.com/hugo-mods/iconsGet the module (also upgrades existing one):
hugo mod get -u
This might take some time, as it will fetch all potentially usable icons.
| Icon Family | Identifier Prefix |
|---|---|
| Font Awesome Solid | fas |
| Font Awesome Regular | far |
| Font Awesome Brands | fab |
Please also have a look at the recommended CSS for styling.
hugo-mod-icons can be used in various ways that depend on your preferences and context.
To master this mod, it is advisable to read through every pattern and then decide which one works best for you.
This pattern is especially useful for smaller sites/prototypes where you can easily pass around the page's context.
Reference icons with:
<body>
<!-- [...] -->
<h1>I {{ partial "icon" (dict "context" . "name" "fas heart") }} hugo-mod-icons!</h1>
<!-- [...] -->
</body>Finally, place the actual data (non-visible) at the very end of the body:
<body>
<!-- [...] -->
{{ partial "icon-data" . }}
</body>It's important that the context is the same as the one passed to the first partial "icon",
which is sometimes a bit tricky, hence the next pattern has been invented.
💡 The module will automatically keep track of all your referenced icons and only add the ones that are actually needed ONCE. No matter how many times you reference one and the same icon.
This pattern is more advanced and especially suitable for larger sites or themes. It requires maintaining all the icons you want to use in a separate icons.yaml file in the data folder, e.g.:
fas heart:You can omit the part after : if you just want to add the icon without renaming it,
but if you'd like to use heart instead of fas heart, you can do the following:
heart: fas heartThe bonus you get is that you can easily exchange fas heart with another ❤️-like icon at a later time!
Next, you reference the icon like:
<body>
<!-- [...] -->
<h1>I {{ partial "icon" "heart" }} icons!</h1>
<!-- [...] -->
</body>Finally, place the actual data (non-visible) at the very end of the body just as in the first pattern:
<body>
<!-- [...] -->
{{ partial "icon-data" . }}
</body>💡 What makes this pattern awesome is that it scales well and that it does not need context for referencing icons. The only downside is that you need to additionally maintain the data file.
You can also use this mod from within your content files with the icon shortcode:
---
title: "My post"
---
Lorem ipsum and so on...
> tldr: `hugo-mods` rock {{< icon "guitar" >}}To be continued. Documentation about mixing patterns and icon loaders will follow here.
Please also check out the exampleSite which you can examine and e.g.
launch via hugo serve exampleSite.
