Browse Courses

Creating Modules

August 16, 2025 3 min read Docs

This guide explains how to create and manage Hugo modules, including the structure, configuration, and best practices for module development.

On this page

This guide explains how to create and manage Hugo modules, including the structure, configuration, and best practices for module development. Learn how to package layouts, assets, and shortcodes into reusable modules that can be shared across multiple Hugo sites.

Create and Initialise a Reusable Hugo Module

Reusable Hugo modules allow you to package layouts, assets, shortcodes, and configuration logic into a versioned, composable unit. This step walks you through initializing your module, structuring it correctly, and preparing it for use in other Hugo sites.

Pre-requisites

Before you begin, ensure you have:

  • Hugo installed (preferably the extended version)
  • Go installed (Hugo Modules use Go Modules under the hood)
  • A Git repository (public or private) to host your module

Directory Structure

Create a new folder for your module, ideally named after the module itself:

1mkdir ags-mcq && cd ags-mcq

Inside this folder, you’ll eventually include:

 1ags-mcq/
 2├── go.mod                      # Required: declares module path
 3├── layouts/
 4│   └── shortcodes/             # Shortcodes used by consuming sites
 5├── assets/
 6│   └── hb/modules/agsayyed/    # Custom assets (e.g., JS, CSS, images)
 7├── static/
 8│   └── sounds/                 # Static files (e.g., audio clips)
 9├── data/                       # Optional: structured data files
10└── README.md                   # Strongly recommended: usage guide
11└── config.toml                 # Required: default params and mounts

This structure ensures your module is composable and override-friendly when imported into a Hugo site.

Initialize the Module

Run the following command inside your module directory:

1hugo mod init github.com/agsayyed/ags-ags-mcq

This creates a go.mod file like:

1module github.com/agsayyed/ags-ags-mcq
2
3go 1.23.2
  • The module path should match the Git repository URL.
  • This enables Hugo to fetch and version your module correctly.

Module Structure

  • layouts/shortcodes/: Shortcodes are the primary interface for reusable logic. Placing them here makes them discoverable by Hugo.
  • assets/: For SCSS, JS, or image pipelines. Hugo processes these via its asset pipeline.
  • static/: For files served directly (e.g., audio clips used in ags-mcqs).
  • go.mod: Required for module resolution and versioning.
  • README.md: Helps consumers understand how to use your module.
  • config.toml: Contains default parameters and mounts for the module.

Config.toml

Once your module is initialized and structured, the next step is to define its configuration. This includes declaring dependencies (other modules), mounting directories, and setting default parameters that consuming sites can override.

The config.toml file is crucial for defining default parameters and mounts for your module. Here’s an example:

 1# config.toml
 2
 3[module]
 4hugoVersion = { extended = true, min = "0.110.0" }
 5
 6[[module.imports]]
 7path = ""
 8
 9[[module.mounts]]
10source = "layouts"
11target = "layouts"
12
13[[module.mounts]]
14source = "assets/hb/modules/agsayyed"
15target = "assets/hb/modules/agsayyed"
16
17
18[params.hb]
19bootstrap.enable_library = true
20
21[params.ags-mcq]
22enable = true
23soundPath = "sounds/"

Explanation of Each Section

  • [module]

    • Declares minimum Hugo version and whether extended features (e.g. SCSS) are required.

  • [[module.imports]]

    • Declares external modules your module depends on.
    • These will be resolved via go.mod when your module is imported.

  • [[module.mounts]]

    • Maps your module’s folders into Hugo’s virtual filesystem.
    • This makes your shortcodes, assets, and static files available to the consuming site.

  • [params]

    • Provides default values for configuration keys used in your shortcodes or partials.
    • These can be overridden by the consuming site.

Best Practices

  • Keep your mounts minimal and purposeful. Avoid mounting content/ unless you’re shipping starter content.
  • Use namespaced parameters (e.g., params.ags-mcq) to avoid collisions.
  • Document expected parameters in your README.
  • Avoid hardcoding site-specific values in your module.

🔗 References

FAQs