Design

This Hugo theme component is designed to be used with the Hugo Pipes feature. It offers ways to have modules add their own assets or particles to JavaScript and Stylesheet pipelines.

ℹ️ Note

It’s currently in development and while it’s ready for use, its documentation might lack. Open an issue to find out more or to contribute.

Javascript

Automatic import via GoHugo Pipes

@import 'modder/main';

will import all plugged in Javascripts that are registered via modules. For this to work the @import or initialization call needs to be processed within a GoHugo JS Pipe .

Import via precompiled JS

Stylesheets and SASS

Automatic import via GoHugo Pipes

assets/scss/plugins.scss imports all plugged in stylesheets that are registered via modules. For this to work the file needs to be processed in the layout file and then imported from your GoHugo SASS pipe

{{- $sassTemplate := resources.Get "scss/plugins.scss" -}}
{{- $style := $sassTemplate | resources.ExecuteAsTemplate "plugins.scss" . | css.Sass -}}

Afterward you can concatenate it to your own styles with $style and complete processing.

Import via precompiled SASS

For instance for use within WebPack.

Probably like this:

Run hugo server, then run

node public/modder-create-scss.js

This should have created a file in assets/scss/plugins_generated.scss that can be imported via

@import 'plugins_generated'

This GoHugo module streamlines the addition of SVG-based icon sets to your Hugo website, utilizing the efficient method of defining icons once using <symbol> and reusing them with <use>. By default, the module includes icon sets as an example, but is designed to support any SVG icon set you wish to integrate.

Key features

• Flexible Icon Integration: Add any SVG-based icon set to your website.
• Efficient Caching Mechanism: Icons are defined once and reused, improving performance.
• Bootstrap Icons Included: The Bootstrap Icons set is provided by default for immediate use and as an example for integrating other icon sets.

Documentation links

• SVG <symbol> Element: MDN Documentation
• SVG <use> Element: MDN Documentation

Included icon sets

• Bootstrap Icons
• Tabler Icons

Usage

Adding icons

To use an icon in your layout, call it as a partial in your templates. The example below demonstrates how to include a Bootstrap icon, but the same method applies to any SVG icon you add to the module:

{{- includes.Partial "icon.html" "arrow-right" -}}
{{- includes.Partial "icon.html" (dict "icon" "arrow-right") -}}

Another option is to include the icon as a shortcode from your content files:

{{< icon "arrow-right" >}}

Development mode

When running your Hugo site in development mode, the module provides sample pages listing all available icons from the included sets:

• Access Bootstrap Icons at http://localhost:1313/icons/bootstrap-icons/.

Adding custom icon sets

This module is designed to support any SVG-based icon set. To add a new set:

1. Place your SVG icons in the appropriate directory within your Hugo site.

2. Add a configuration to the config.toml file, specifying the path to your icons and the icon set name:

   • TOML
   • YAML
   • JSON
   • (click to select config format)
   • COPY

   [dnb]
     [dnb.icons]
       default = 'custom'
       [dnb.icons.custom]
         path = 'node_modules/custom-icon-set/icons/%s.svg'
         slug = 'custom'
   

   dnb:
     icons:
       custom:
         path: node_modules/custom-icon-set/icons/%s.svg
         slug: custom
       default: custom
   

   {
      "dnb": {
         "icons": {
            "custom": {
               "path": "node_modules/custom-icon-set/icons/%s.svg",
               "slug": "custom"
            },
            "default": "custom"
         }
      }
   }
   

   Make sure to replace custom with the name of your icon set and node_modules/custom-icon-set/icons/%s.svg with the path to your icons. The %s placeholder is being replaced with the icon name when the icon is called.

   The slug parameter is used to reference the icon set in your layouts and shortcodes and add classes to format them. The classes created in the preceding sample would be icon--custom and icon--iconname where iconname is the icon loaded.

3. Reference your custom icons using the partials methods preceding.

Migration guide

From versions 1.2024.0 and below

Older versions of this module may have added icons directly each time a shortcode or partial was called, leading to performance issues. The current version improves upon this by including icons once and then reusing them by reference. To migrate to the latest version:

• There are no breaking changes; update your partials and shortcodes according to the usage guide.
• Replace direct calls to specific icon sets (for example bsicon, heroicon) with calls to icon.html, passing the icon name or setting a global icon type.
• Do not cache the icon-partial calls in your layouts; the module handles this for you.