Community help to confirm my website module is configured properly

[Floren]

I’m very new at Hugo, so I spent some time reading the documentation, prior opening this thread.

I have a very specific website design, with what I call projects. Currently I have /docs and /k3s-cluster projects in my repository, both using the same hextra theme. Basically, the website module I created stores the common elements of each project, allowing me to avoid settings and related code duplication. Due to the unique nature of each project, I cannot merge everything into a single directory. For example, the menu related settings are specific to each project.

This is how I implemented the website module:

• Create /go.mod and /hugo.yaml at repository root, as well the other theme common elements, like i18n and layouts.
• Into /docs/hugo.yaml configuration, insert the module imports:

module:
  hugoVersion:
    extended: true
    min: 0.125.0
  imports:
    - path: github.com/axivo/website
    - path: github.com/imfing/hextra

• Run hugo --gc --minify -s ./docs from repository root, to validate the site is created properly, which will also update /docs/go.mod and /docs/go.sum with correct module versions.

The reason I started this thread is because prior creating the website module, the hextra theme was functioning properly, while preserving the duplicated code in each project directory. Now, certain theme elements are not rendered correctly, which makes me believe I missed something into my website module configuration.

Please see PR sample to replicate the issues locally, if desired. Switch to feature/tutorials branch, start the server and visit the Tutorials page to notice two broken shortcodes, out of seven used:

cd docs
hugo server --buildDrafts --disableFastRender --logLevel debug

For reference, I created also an issue into theme repository.

[Floren]

I actually need some documentation clarification how modules are combined. With the following configuration files structure:

├── docs
│   ├── content
│   │   └── _index.md
│   ├── go.mod
│   ├── go.sum
│   └── hugo.yaml
├── go.mod
└── hugo.yaml

Is the website module configuration located at root level combined with the /docs theme configuration, or do I have to explicitly define a combination of both, with --config ../hugo.yaml,./hugo.yaml?

[razon]

You’ll need to import the corresponding module, module’s configuration will be merged into the site. Full example as follows.

➜ tree
├── common
│   ├── go.mod
│   └── hugo.toml
└── docs
    ├── go.mod
    ├── hugo.toml
    └── layouts
        └── index.html

3 directories, 5 files

➜ cat common/go.mod 
module example.org/me/monorepo/common

go 1.18

➜  cat common/hugo.toml 
[params]
foo = "bar"

➜ cat docs/go.mod 
module example.org/me/monorepo/docs

go 1.18

replace example.org/me/monorepo/common => ../common

require example.org/me/monorepo/common v0.0.0-00010101000000-000000000000 // indirect

➜ cat docs/hugo.toml 
[[module.imports]]
path = "example.org/me/monorepo/common"

[params]
fizz = "buzz"

➜ cat docs/layouts/index.html 
{{ warnf "%#v" site.Params }}

➜ cd docs && hugo
hugo v0.125.7-b1d808bc373f53ad37c8966bb02a6aea095db5f8+extended linux/amd64 BuildDate=2024-05-08T14:46:24Z VendorInfo=gohugoio
WARN  maps.Params{"fizz":"buzz", "foo":"bar"}

As the example shown, the docs site import the common module and access the foo parameter from it.
Please change the module path as your own.

[Floren]

@razon Thank you for useful information. So basically, there is no way for me to keep the common information at repo root level?

[razon]

It’s similar, assume the root level is shareable module, then just move the common folder to root level, and replace all relative common module’s path, please tweak the replace directive on docs/go.mod.

Create files and test it locally, it’s just an example with only 5 files.

[Floren]

@razon This is what I have in /docs/go.mod:

module github.com/axivo/website/docs

go 1.22.2

require (
	github.com/axivo/website v1.0.0 // indirect
	github.com/imfing/hextra v0.7.4-0.20240523223646-d43ac6649463 // indirect
)

When you mention to tweak the replace, what would be the correct format? Something like:

module github.com/axivo/website/docs

go 1.22.2

replace github.com/axivo/website => ../
require (
	github.com/axivo/website v1.0.0 // indirect
	github.com/imfing/hextra v0.7.4-0.20240523223646-d43ac6649463 // indirect
)

This is for my learning experience, I believe your proposed solution to create a common module is a much cleaner solution, where all related files are grouped inside a directory.

[Floren]

@razon

You’ll need to import the corresponding module

I successfully implemented your suggestion and everything is functional, except that I’m still forced to pass the --config parameter:

hugo server -s ./docs -D --disableFastRender \
  --config ../global/hugo.yaml,./hugo.yaml

Is there way to avoid defining the --config parameter?

[razon]

Please describe the error in detail, I just clone your repo and test locally, seems everything is OK.

I put the following code in homepage to read parameter from global module.

{{< param "blog.list.displayTags" >}}

axivo/website/blob/7f9056ffd5af56214e97bfdeca38df4bf7f9bc7e/global/hugo.yaml#L27

Command without specifying --config

hugo server -s ./docs -D --disableFastRender

Some references:

1. Merge configuration from themes

[Floren]

@razon, the site works partially, if you omit the --config switch. Thank you for cloning the repo, it will be easy to test on your side. I understand what you are saying, if /global/hugo.yaml would not load, you would not be able to print the blog.list.displayTags value on frontpage.

As a side note, the theme developer mentioned into the issue I opened that I need to pass the --config switch, which is clearly not the case. I was wondering if you can take few minutes of your busy time and determine the root cause of the problem.

Running:

hugo server -s ./docs -D --disableFastRender

Produces a partially broken site:

While, running:

hugo server -s ./docs -D --disableFastRender \
    --config ../global/hugo.yaml,./hugo.yaml

Produces a functional site (note the Latest Projects header):

[razon]

Some configuration will not be merged from modules/themes into site, in this case, you need to set markup._merge as deep (or shallow, I didn’t test).

// docs/hugo.yaml
markup:
  _merge: deep

See the reference on previous reply for details.

[Floren]

@razon, thank you for the useful information, it fixes the problem. Both _merge types you mentioned work. I’m going to use shallow, to avoid any possible merging conflicts.

[Floren]

@razon just for my learning experience, how did you determine the issue was related to markup?

[razon]

You’ll find out there is something like raw html omitted on source code if using default markup setting.