search

squidfunk / mkdocs-material

Documentation that simply works
https://squidfunk.github.io/mkdocs-material/
MIT License
20.98k stars 3.55k forks source link

Versioning: Invalid Base URL on 404 Page Build #7629

Closed mdapena closed 3 weeks ago

mdapena commented 3 weeks ago

Context

While working on my documentation with MkDocs Material and Mike's versioning integration, I encountered an issue after fixing some broken links. I noticed that the 404-page wasn’t functioning as expected; for example, the versioning selector was missing, and the search input was stuck on initializing.

To determine if this was just a problem with my setup, I did some digging and found that other documentation sites using Mike's versioning integration were experiencing the same issue. Here are a few examples:

While searching for errors, I discovered that when the 404-page is loaded, it throws the following error (or something similar):

Uncaught Error: 
    zr index.ts:80
    zr index.ts:73
    RxJS 74
    ai index.ts:82
    ui index.ts:110
    xs bundle.ts:238
    <anonymous> bundle.ts:238
    <anonymous> bundle.ts:318
    ...

After further investigation, I found that the 404.html page was being built incorrectly. Its resource paths were prefixed with /package_name/{version or alias} or just /{version or alias} in some cases, even though it should have the same resource paths as the index.html page since it’s in the root directory of that version build. As a result, the 404-page couldn’t find its resources, which led to the errors I was encountering.

While trying to confirm and fix this issue, I found a temporary workaround: manually updating the resource paths in the 404.html page to match the actual file locations in the build (similar to those in index.html). You can see the workaround in action in my documentation here:

Bug description

When using MkDocs Material with Mike's versioning integration, the 404.html page is generated with an incorrect base URL. Specifically, the base URL has a prefix of /package_name/{version or alias} or just /{version or alias} in some cases, even though the file is located at the root level of the version build. It should have the same resource paths as the index.html page.

This incorrect base URL results in broken links for essential resources, such as JavaScript assets, leading to functionality issues on the 404.html page, including a non-working search bar and a missing versioning selector.

This issue only occurs when Mike's versioning is enabled; the 404-page functions correctly without it. As mentioned in the context section, I confirmed this issue and found a workaround by manually updating the resource paths to remove the invalid prefix.

PS: Thank you for this amazing package! 😄

Related links

Reproduction

While I will include a reproduction.zip file with relevant information about my system and other important details, creating a fully functional reproduction is not feasible. Running mike serve locally requires a repository with a deployed and configured gh-pages branch. (See Viewing Your Docs.)

However, the example-versioning provided in the MkDocs Material documentation serves as a suitable reproduction example, as it focuses solely on the versioning setup:

Steps to reproduce

  1. Fork the example-versioning repository from MkDocs Material: github.com/mkdocs-material/example-versioning.
  2. Follow the setup instructions in the README file to configure the versioning (See How to set up versioning).
  3. Run the command mike serve to start the local server or go to the deployed gh-pages.
  4. Trigger the 404 error page by entering an invalid URL (this will only work if the GitHub Pages is configured to use the documentation 404 page) or simply go to ...gh-page-url/404.
  5. Once on the 404-page, check the console for any error messages or try using the search bar at the top.

Browser

No response

Before submitting

squidfunk commented 3 weeks ago

Thanks for reporting. The base_url is set by MkDocs, which is controlled by mike, so I'm very confident that this is an upstream issue. Our mike integration only loads the versions.json ands renders the version selector. The fact that search is broken, denotes that the base_url is invalid. Since the 404 page needs an absolute base URL (as any path must map to it), the base URL is invalid and the assets can not be loaded. There seems to be an upstream issue:

This issue only occurs when Mike's versioning is enabled; the 404-page functions correctly without it.

Please take this discussion upstream, unless you can proof that this happens solely with Material for MkDocs, and works for other themes. I'm confident that this is a mike issue, not a MkDocs or Material for MkDocs issue.

squidfunk commented 3 weeks ago

Other than that, thank you for investing the time to write up a very detailed issue and explanation. Please note that we're developing a new way for working with multi-project builds, which includes multi-language and versioning. Our goal is to provide versioned documentation that just works locally, and does not need to be deployed to function.

mdapena commented 3 weeks ago

Thanks for the quick reply! That was fast⚡

Yeah, it makes total sense that if the base_url is controlled by MkDocs and the mike package is the one that uses it to build the 404 page, then this is definitely an upstream issue. I’ll take this to mike's issue tracker and see if I can find the root cause.

mdapena commented 3 weeks ago

Other than that, thank you for investing the time to write up a very detailed issue and explanation. Please note that we're developing a new way for working with multi-project builds, which includes multi-language and versioning. Our goal is to provide versioned documentation that just works locally, and does not need to be deployed to function.

Wow! I wasn’t aware of this, but it sounds amazing! I really appreciate you sharing this information and your commitment to improving the project. I’m excited to see how it all comes together!