https://github.com/foo-dogsquared/hugo-mod-simple-icons
A Hugo module for the Simple Icons icon set.
https://github.com/foo-dogsquared/hugo-mod-simple-icons
hugo-mod hugo-module simple-icons
Last synced: 6 months ago
JSON representation
A Hugo module for the Simple Icons icon set.
- Host: GitHub
- URL: https://github.com/foo-dogsquared/hugo-mod-simple-icons
- Owner: foo-dogsquared
- License: mit
- Created: 2020-10-26T17:34:25.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-05-22T23:19:58.000Z (11 months ago)
- Last Synced: 2024-05-23T00:28:12.885Z (11 months ago)
- Topics: hugo-mod, hugo-module, simple-icons
- Language: Nix
- Homepage:
- Size: 76.2 KB
- Stars: 8
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
= hugo-mod-simple-icons
:toc:
A https://gohugo.io/hugo-modules/theme-components/#readout[Hugo theme component] for https://github.com/simple-icons/simple-icons/[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 https://gohugo.io/news/0.75.0-relnotes/[getting more support for JavaScript-based workflows] (and https://discourse.gohugo.io/t/esbuild-looks-like-we-can-finally-get-solid-hugo-modules-support/28757[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 https://golang.org/dl/[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.
[source, toml]
----
[[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 link:https://github.com/simple-icons/simple-icons/releases/tag/6.7.0[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 https://github.com/golang/go/wiki/Modules#how-to-upgrade-and-downgrade-dependencies[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 https://simpleicons.org/[website], https://github.com/simple-icons/simple-icons/tree/develop/icons[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 https://gohugo.io/hugo-pipes/introduction/[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 https://gohugo.io/templates/data-templates/#the-data-folder[the data folder] where you can use it (at `$.Site.Data.simple-icons`) to create https://gohugo.io/templates/data-templates/[data templates].
The following shows how to get an icon from the set.
[source, go]
----
{{ $icon := resources.Get "svg/simple-icons/github.svg" }}
{{ $icon.Content | safeHTML }}
----
== License
The Hugo theme component is licensed under MIT license.
Please see the link:./LICENSE[license file] for the full text.
The Simple Icons icon set is licensed under https://creativecommons.org/publicdomain/zero/1.0/[Creative Commons Zero 1.0 Universal Public Domain].
See the https://github.com/simple-icons/simple-icons/blob/develop/LICENSE.md[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 link:https://docs.github.com/en/free-pro-team@latest/rest[GitHub API] and link:https://stedolan.github.io/jq/[jq] which I've created one in the link:./Makefile[Makefile].
It does need link:https://curl.se/[curl], link:https://stedolan.github.io/jq/[jq], and link:https://www.gnu.org/software/make/[GNU Make] (of course) for this to work.
The documentation uses link:https://asciidoctor.org/[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 link:https://nixos.org/[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 link:https://direnv.net/[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 https://github.com/simple-icons/[Simple Icons] for keeping the icon set top notch.
* The team and community behind https://gohugo.io/[Hugo] for creating a great project that is maintained in top condition for a very long time.
* The maintainers of https://github.com/gohugoio/hugo-mod-bootstrap-scss-v4[Bootstrap v4 Hugo module] as a template for the Hugo module thing.