search

google / docsy

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

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

Open mlange-42 opened 4 months ago

mlange-42 commented 4 months 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 4 months 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 4 months 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 3 months 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 3 months 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 3 months 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 3 months 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 3 months 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.
mlange-42 commented 2 months ago

Thanks @deining, this fixes the layout issue.

However, all the link are broken now, as the folder where the site is served is not included. E.g. the test link I inserted in the minimal reproducing example [test link](/how-to-contribute/) becomes:

https://mlange-42.github.io/how-to-contribute/

instead of (as with canonifyURLs):

https://mlange-42.github.io/knowledge/how-to-contribute/

The same with hugo serve. Using --baseURL ... does not have an effect here.