Site layout broken after upgrade

[Backspaze]

I'm in the process of building a documentation site, which is only going to be available on my LAN. It contains info that's not supposed to be public, so I have no repo to share. I also haven't been able to find a way to replicate the issue in a good way.

I figured that while I troubleshoot this to try and find the issue, I'll post a question here and see if someone might be able to help me figure out what's going on.

Before the upgrade, the site worked fine.

After the upgrade:

• It does not detect dark mode
• It removes the top menu with the logo
• The main content is wider
• The default purple button with a link to an example guide is back, even though it's still commented out in \layouts\index.html.

The only way to access any part of the rest of the site is through the link card I've placed on the main page. But, that link only leads to the main article in the documentation, which also:

• Has no top menu with the logo
• The content is again stretched across the whole width of the screen.

Some censored screenshots below to illustrate the issue more clearly.

Main page before the upgrade

Main page after the upgrade

Main docs page before the upgrade

Main docs page after the upgrade

Environment before the upgrade

OS: Windows 10 Pro 22H2 (19045.6093) 
Hugo: v0.145.0 extended 
NPM: 11.4.2
Node: 20.19.3

Package.json

  "dependencies": {
    "@tabler/icons": "^3.12.0",
    "@thulite/doks-core": "^1.8.1",
    "@thulite/images": "^3.3.1",
    "@thulite/inline-svg": "^1.1.0",
    "@thulite/seo": "^2.4.1",
    "thulite": "^2.5.0"
  },
  "devDependencies": {
    "prettier": "^3.3.3",
    "vite": "^7.0.5"
  },
  "engines": {
    "node": ">=20.11.0"
  }

Environment after the upgrade

OS: Windows 10 Pro 22H2 (19045.6093) 
Hugo: v0.148.1 extended 
NPM: 11.4.2
Node: 20.19.3

Package.json

  "dependencies": {
    "@tabler/icons": "^3.34.1",
    "@thulite/doks-core": "^1.8.3",
    "@thulite/images": "^3.3.1",
    "@thulite/inline-svg": "^1.2.0",
    "@thulite/seo": "^2.4.1",
    "thulite": "^2.6.3"
  },
  "devDependencies": {
    "prettier": "^3.6.2",
    "vite": "^7.0.6"
  },
  "engines": {
    "node": ">=20.11.0"
  }

To upgrade, the first thing I did was run the command from the upgrade documentation. And upgraded Hugo by replacing the 0.145.0 hugo.exe with the 0.148.1 version. After this, the main docs page mentioned above had no sidebar menu, no TOC, no top menu, and the main content covered the entire width of the screen.

Since the upgrade command above does not cover all dependencies, I also tested with the command below.

npm install @tabler/icons@latest @thulite/doks-core@latest @thulite/images@latest @thulite/inline-svg@latest @thulite/seo@latest thulite@latest

It made a difference in that the sidebar menu and TOC returned on the main docs page, but everything was still stretched out over the entire width of the screen, and it still does not detect dark automatically, and there are more CSS issues, such as callouts not having the correct color for both the card and text.

I've ran npx shx rm -rf public resources hugo_stats.json .hugo_build.lock, but it made no difference.

I've tried editing package.json with different combinations of the versions of the dependencies, and removed the ^ to make sure that it installs a specific version, but it made no difference, or I couldn't find a combination that worked with the latest version of Hugo.

I've tried other versions of Hugo, such as v0.146.0, but it made no difference. Running Hugo v0.145.0 does not work after upgrading Doks and it's dependencies as per above.

The console in the browser shows errors about the search feature, but no further errors. Considering that this looks like a CSS issue, I figured that I would see a bunch of CSS related errors there, but nope.

I've done some edits to the theme, but I don't understand how this upgrade can break the whole layout, especially as it's only a patch release.

Any help in figuring this out is much appreciated. I've hit a wall in my troubleshooting for the moment, and will proceed with the downgraded version until I can get this sorted out.

[h-enk]

I think you've hit a module mounting order issue — I upgraded the Doks site and hit a similar /the same one.

What worked for me, update the layouts part order in config/_default/module.toml —

From:

## layouts
[[mounts]]
  source = "node_modules/@thulite/doks-core/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/core/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/seo/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/images/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/inline-svg/layouts"
  target = "layouts"

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

To:

## layouts
[[mounts]]
  source = "layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/doks-core/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/core/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/seo/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/images/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/inline-svg/layouts"
  target = "layouts"

Can you let me know if this works for you? Then I will put out a fix release — thx!

[Backspaze]

Thanks, that fixed the layout issue! So the order of the mounts is apparently important.

In your example, the only thing that's changed is that the last entry was moved to the top. My modules were listed in a different order, as shown in the hidden tag below. I tried moving only the last one to the top, but that didn't fix the issue, so I copied your example to get all of them in the correct order.

Details

## layouts
[[mounts]]
  source = "node_modules/@thulite/core/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/seo/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/images/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/doks-core/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/inline-svg/layouts"
  target = "layouts"

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

I think I also figured out why the pill button reappeared. In the old version, I had edited \layouts\index.html by commenting out the button as shown below. This worked to make it disappear in the previous version. It's still commented out in that file after the update, but there's obviously something else that renders it now.

After digging around in the folders, I found \node_modules\@thulite\doks-core\layouts\home.html, which seems to have taken over as the new template for the home page. I copied that file to \layouts\home.html, and commented out the button in the same way, which made the button disappear again.

I'm guessing that I found the right way to fix this, and that I can delete the old \layouts\index.html?

<div class="col-lg-9 col-xl-8 text-center">
  <p class="lead">{{ .Params.lead | safeHTML }}</p>
    <!--<a class="btn btn-primary btn-cta rounded-pill btn-lg my-3" href="/docs/{{ if site.Params.doks.docsVersioning }}{{ site.Params.doks.docsVersion }}/{{ end }}guides/example-guide/" role="button">{{ i18n "get_started" }}</a>-->
    {{ .Content }}
</div>

[h-enk]

I'm guessing that I found the right way to fix this, and that I can delete the old \layouts\index.html?

Yes that's correct! For more background, see New template system in Hugo v0.146.0

I'm also working on the documentation, including an upgrade guide — available soon

[h-enk]

I fixed it. Note, I also included excludeFiles = "home.html" — livereload now works properly when changing layouts/home.html

## layouts
[[mounts]]
  source = "layouts"
  target = "layouts"

[[mounts]]
  # Exclude 'home.html' to avoid conflicts with a custom home page layout defined in the local 'layouts' directory.
  excludeFiles = "home.html"
  source = "node_modules/@thulite/doks-core/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/core/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/seo/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/images/layouts"
  target = "layouts"

[[mounts]]
  source = "node_modules/@thulite/inline-svg/layouts"
  target = "layouts"

[h-enk]

Please see the Doks v1.8 upgrade guide