Svg icons can be used from Hugo with a shortcode

Demo

Here is a short preview:

This icon: was insert with this simple shortcode: {{< ico "world" >}}

This shortcode can be combined with every other Markdown features:

Lorem ipsum sint dolor minim non eu labore occaecat minim. Consectetur culpa amet sunt aliqua ipsum non Lorem incididunt ut officia aliqua consequat id veniam.

  • Write an email to Emma
  • Lorem ispum warning lorem etc

Features:

More than 4000 open source icons are shipped with the shortcode.

Included icon sets:

  • Tabler.io – a huge collection of 3000+ icons designed by Paweł Kuna
  • Boxicons provides 1600+ icons with Regular and Solid variantes.
  • The collection is completed with Heroicons: 300 hand-crafted icons by the makers of Tailwind CSS

and there’s many more available.

Note that adding these 4000 icons to your Hugo project represent less than 3Mo, SVG is magic!

The core precepts of this exploration were:

  • Simple: the basic syntax must be simple to remember and type, while advanced features are available, but optionnal.
  • Performant: we do not want to use heavy font files. Here we load only icons that are actually used in the page, and we use SVG inlining to save network requests.
  • Accessible: we automatically inject aria-hidden="true" in each SVG file we load.
  • Extensible: easily add custom icons or set custom CSS classes.
  • Free and open source: see the Source code and the Roadmap

Installation

  1. Set up this Shortcode collection as Git submodule:
git submodule add https://gitlab.com/Roneo/hugo-shortcode-roneo-collection.git themes/hugo-shortcode-roneo-collection
  1. Load the module from config.toml:
theme = ['hugo-shortcode-roneo-collection', 'YourCurrentTheme']

Done!

You can now use {{< ico "heart" >}} and you’ll get that: Congrats!

First use

Available icons can be found in the folder themes/hugo-shortcode-roneo-collection/assets/svg

To use icons from the default folder, only the name is required:
{{< ico "moon" >}} will load default/moon.svg

Other folders need a second parameter: to use the icon coffee.svg from the boxicons folder, use this shortcode :
{{< ico "coffee" "boxicons" >}} – and you’ll get this: .

Adding custom icons

Create a folder assets/svg/whatever at the root of your project and any icon in there will be available from the shortcode.

Note that calling an invalid / missing icon breaks the build, so don’t forget to commit and upload new icons along with your content.

Advanced usage

Use icons in template files

Default icons can be used in theme files too, with the following partial:

{{ partial "ico" "star" }}

Use custom CSS classes

Each icon is already loaded with specific CSS classes to easily target them: this icon: comes with the following classes: heroicons ico ico-bell.

You can also add custom CSS classes this way:
(“theme” is here the name of the folder containing the icon)

{{< ico icon="heart" theme="heroicons" class="red medium" >}}

Unamed parameters are supported too, as long as your parameters respect the same order:

{{< ico "heart" "heroicons" "red medium" >}}

Update code & icons

You can update this theme component with the following command:
(Make sure to run in a clean repo to avoid Git conflicts)

git submodule foreach git pull

References

This was inspired by the work of Utkarsh Verma

Related projects:

Documentation:

What’s next?

Follow future releases on Github and Gitlab.

Feel free to get in touch in the comments or drop me an email