search

google / docsy

A set of Hugo doc templates for launching open source content.
https://docsy.dev
Apache License 2.0
2.55k stars 888 forks source link

Broken JS and CSS paths with `hugo serve` since Hugo v0.123.0 #2053

Open mlange-42 opened 1 month ago

mlange-42 commented 1 month ago

Environment

Problem

I have a Docsy site that is served in a folder of a domain, not on its root, so baseURL = "https://example.com/knowledge/"

When running hugo serve, the layout is completely broken because wrong URLs for built-in JS and CSS files are generated. Note the duplicate knowledge:

<script src="http://localhost:1313/knowledge/knowledge/js/main.js"></script>

The same problem occurs with scss/main.css, offline-search-index.json and js/click-to-copy.js.

With Hugo v0.122.0, it works fine:

<script src="http://localhost:1313/knowledge/js/main.js"></script>

It also seems that the problem does not occur when building the site normally, without serve. However, I don't want to test it on the real site, risking breakage.

chalin commented 1 month ago

Thanks for filing an issue. Can you share a link to your repo? Or provide a small repro? I'm overloaded and won't have the time to look into this for a while. @fekete-robert @deining @LisaFC - might any one of you have time to look into this?

mlange-42 commented 1 month ago

The original repository is not public, so I made a simplified version without the actual content: https://github.com/mlange-42/knowledge

It turns out that the problem does not only occur with the hugo serve command, but also with simply hugo. See the rendered version here: https://mlange-42.github.io/knowledge/

huanlin commented 1 month ago

Hi @mlange-42 , How about modify the baseURL in your Hugo configuration file as below:

baseURL = "/"

This should fix the JS and CSS path errors when you run hugo server command locally.

Then, in your CI/CD pipeline, try to use the --baseurl option as below:

hugo --baseURL https://mlange-42.github.io/knowledge/

If I understand it correctly, you can also set environment variable HUGO_BASEURL in your CI/CD pipeline. Reference: Configure with environment variables

Hope this helps.

fekete-robert commented 1 month ago

@huanlin 's advice is good, that's what usually I use as well. A slight alternative is to have different config files for the different environments (https://gohugo.io/getting-started/configuration/#configuration-directory) - this is useful if there are other parameters that you want to change between local/production, not only the baseurl. Also, hugo/docsy does some optimizations on the output if the environment is production.

mlange-42 commented 1 month ago

@huanlin @fekete-robert Many thanks for advising this workaround. Will give it a try. However, as the non-serve version is also broken, I guess hugo --baseURL https://mlange-42.github.io/knowledge/ won't help.

As it worked well before v0.123.0, I still think this is a bug, not sure if on the side of Hugo or Docsy.

huanlin commented 1 month ago

@huanlin @fekete-robert Many thanks for advising this workaround. Will give it a try. However, as the non-serve version is also broken, I guess hugo --baseURL https://mlange-42.github.io/knowledge/ won't help.

As it worked well before v0.123.0, I still think this is a bug, not sure if on the side of Hugo or Docsy.

Hey @mlange-42 , the reason I think it is a normal way to do it, is because that is exactly what I did for my Hugo+Docsy websites. The target servers have different environments, so I use hugo --baseURL in my CI/CD pipeline to generate and deploy my websites.

However, it's just me. Maybe other guys also find that it is a bug.

deining commented 1 month ago

As it worked well before v0.123.0, I still think this is a bug, not sure if on the side of Hugo or Docsy.

I investigated this issue, thanks for sharing the repo. The culprit is this setting in your config.toml:

canonifyurls = true

As soon as you set this setting to false or remove the line alltogether, everything works as expected.

From the official documentation:

Canonical URLs

This is a legacy configuration option, superseded by template functions
and Markdown render hooks, and will likely be removed in a future release.