Adding a [hugo-module]/exampleSite

tips & tricks
1

Sometimes it’s useful to add a site to test out/preview a Hugo Module (theme/theme component). I have had a rather hacky setup with this before adding a /exampleSite folder.

Yesterday I came up with a much simpler and more robust setup that I thought I should share. It falls into the category why did I not think about this before:

It’s all in this commit:

But the gist of it is:

  • Import the modules(s) you’re using in the exampleSite Hugo Module
  • For the module that lives in the folder above, just put a replacement directive in go.mod, e.g. replace github.com/bep/docuapi/v2 => ../
3 Likes
3

I’ve been doing something similar for a long time (below) and wonder if there is a reason to prefer one method over the other.

In the exampleSite directory:

go.mod

module github.com/danielfdickinson/minimal-test-theme-hugo-dfd/exampleSite

go 1.17

Standard go.mod in the main (theme or module) directory

In exampleSite/config.toml

Note The mounts aren’t necessary if you don’t do the README in assets things. I do that so that I can use the the README asset via a shortcode in a content page (so the module README is in the exampleSite output).

[module]
  # For the example site, we need the _current_ theme module from the same repo (path is relative to themes directory)
  # See https://gohugo.io/hugo-modules/configuration/#module-config-top-level (replacements)
  replacements = "github.com/danielfdickinson/minimal-test-theme-hugo-dfd -> ../.."

  [[module.mounts]]
    source = "static"
    target = "static"

  [[module.mounts]]
    source = "layouts"
    target = "layouts"

  [[module.mounts]]
    source = "data"
    target = "data"

  [[module.mounts]]
    source = "assets"
    target = "assets"

  [[module.mounts]]
    source = "i18n"
    target = "i18n"

  [[module.mounts]]
    source = "archetypes"
    target = "archetypes"

  [[module.mounts]]
    source = "content"
    target = "content"

  [[module.imports]]
     path = "github.com/danielfdickinson/minimal-test-theme-hugo-dfd"

    [[module.imports.mounts]]
      source = "static"
      target = "static"

    [[module.imports.mounts]]
      source = "layouts"
      target = "layouts"

    [[module.imports.mounts]]
      source = "data"
      target = "data"

    [[module.imports.mounts]]
      source = "assets"
      target = "assets"

    [[module.imports.mounts]]
      # Allows us to access the README.md and use it in page (via the ``page-assets`` shortcode in exampleSite)
      source = "README.md"
      target = "assets/README-minimal-test-theme.md"

    [[module.imports.mounts]]
      source = "i18n"
      target = "i18n"

    [[module.imports.mounts]]
      source = "archetypes"
      target = "archetypes"

The full code is here:

This isn’t just for themes though; I use it with all my modules, but use above repo to get some basic layouts so I don’t have tons of layout boilerplate bit rotting in different modules.

For example see:

HTH!