hugo-mod-simple-icons

Table of Contents

Getting started
- Using it in the Hugo site
License
Development guidelines
Acknowledgements

A Hugo theme component for Simple Icons , a free and open source icon set for popular brands. This module enables you to use the icons without getting the icons yourself.

You can still use the icon set with NPM and seeing that Hugo is getting more support for JavaScript-based workflows (and more in the future). Even so, this module is good if you don’t want to install additional tooling.

Note	The following example snippets are in TOML format. Be sure to convert it first into the appropriate format if you’re using other than TOML.

Getting started

As a prerequisite, you need Hugo v0.56 and above (as long as it has the Hugo module feature) and the latest version of Go.

First, you need to initialize your Hugo project as a Hugo module. This can be done by running hugo mod init $HUGO_MODULE_PATH.

Then, you can import the Hugo module in your site config.

[[module.imports]]
  path = "github.com/foo-dogsquared/hugo-mod-simple-icons"

You can also specify the tag by adding @$TAG at the end of the path. The versioning scheme of this module follows the project — e.g., for Simple Icons v6.7.0, you can find a version of the module that has "v6.7.0". The format of the tags of the module is "v${VERSION}". For more information, you can see how to specify Go modules since Hugo modules are built on top of it.

Next, get the dependency by running hugo mod get and to update the component, run hugo mod get -u. (You could also run the server [i.e., hugo server] to download the modules.)

To get the list of icons, simply view the website, see the icons folder from the source itself, and/or search within the repo.

Using it in the Hugo site

Now that you have the theme component in the Hugo project, you have to actually use it. By default, the theme component has the following configuration:

Icon set is available at assets/svg/simple-icons for interacting with resources. From there, you can then get the icon with a simple resources.Get.
The Simple Icons dataset is available as data/simple-icons.json in the data folder where you can use it (at $.Site.Data.simple-icons) to create data templates.

The following shows how to get an icon from the set.

{{ $icon := resources.Get "svg/simple-icons/github.svg" }}
{{ $icon.Content | safeHTML }}

License

The Hugo theme component is licensed under MIT license. Please see the license file for the full text.

The Simple Icons icon set is licensed under Creative Commons Zero 1.0 Universal Public Domain. See the related file for the full details.

Development guidelines

Maintaining this module is quite simple. One of the main core tasks of maintaining this module is simply updating the module to use the latest version of the icon set. It can be done with hugo mod get ${SIMPLE_ICONS_GIT_URL}@${COMMIT} where the commit is the latest commit hash of the repository. Then tidy the related files with hugo mod tidy and you’re done. Fortunately, this can be automated with simple tools and services like the GitHub API and jq which I’ve created one in the Makefile. It does need curl, jq, and GNU Make (of course) for this to work.

The documentation uses Asciidoctor-flavored Asciidoc as the format. The Asciidoctor toolchain is not necessary to install, you just need to know the formatting syntax of it.

If you have Nix installed, you can easily set up the same development environment that I use by running nix-shell shell.nix or nix develop if you have Nix flakes feature enabled.

Tip	You can make setting up the development environment even easier with direnv along with Nix. Just add `echo "use nix" > .envrc && direnv allow` in the project root and you’re good to go!

Acknowledgements

The maintainers of Simple Icons for keeping the icon set top notch.
The team and community behind Hugo for creating a great project that is maintained in top condition for a very long time.
The maintainers of Bootstrap v4 Hugo module as a template for the Hugo module thing.

foo-dogsquared / hugo-mod-simple-icons