Wrong paths in 404 page on mkdocs.org

[froschdesign]

Good:

https://www.mkdocs.org/foo

Bad:

• https://www.mkdocs.org/foo/
• https://www.mkdocs.org/user-guide/foo
• https://www.mkdocs.org/user-guide/foo/

The problem are the paths because it points to the wrong target. Examples:

<link href="css/bootstrap-custom.min.css" rel="stylesheet">
<script src="js/bootstrap-3.0.3.min.js" defer></script>
…
<a href="user-guide/writing-your-docs/">…</a>

The template filter URL does not help here.

<link href="{{ 'css/bootstrap.min.css'|url }}" rel="stylesheet">

https://github.com/mkdocs/mkdocs/blob/master/mkdocs/themes/mkdocs/base.html#L20

Any ideas to prevent the problem on the mkdocs.org and also in the used theme? Thank you in advance!

[waylan]

Is this perhaps a duplicate of #1598? Wether it is a duplicate or not, it is certainly related as that issue discusses many extra considerations when generating error pages and it links to additional considerations from earlier discussions.

In any event, your example doe snot make the problem clear to me. Could you provide an example which contains all of the following information:

1. What is the "bad" URL found in the built error page?
2. What URL should be used instead?
3. What is the URL of the error page when the "bad" URL is incorrect?
4. What template syntax generates the "bad" URL?
5. What is site_url set to in the mkdocs.yaml config file?

Please provide the URL as it appears in the HTML source. In other words, use a text editor to open the built error page (site/404.html) and copy the URL from there.

[froschdesign]

@waylan
I'm sorry, but my first report was unclear. The report is related to mkdocs.org - your own homepage. Because the problem of the wrong path is included there. (I updated my post.)
And everyone who used the same theme or the same code from the theme to included CSS and JS files has the same problem.

All called and wrong generated URLs can be found above. Also the used code.

[polarathene]

@waylan it would be good if this could be mentioned in the official documentation. It can be quite confusing to run into and try identify what is going wrong.

Either MkDocs should detect a root domain at build time (no need for JS), or if resolving the problem isn't viable, the workaround/gotcha (root domain for site_url requires a trailing slash) should be documented for the site_url or 404 page issue.

Updating the mkdocs.yml of this project to add the trailing slash to site_url should also resolve the problem depicted above in images and relevant link examples of the bug.

---

IIRC, not providing a site_url can also result in sitemap.xml being generated with empty entries instead of the actual paths, but that's a different issue.

[waylan]

Updating the mkdocs.yml of this project to add the trailing slash to site_url should also resolve the problem depicted above in images and relevant link examples of the bug.

This is a tricky one to debug because the dev server overrides the setting and makes it impossible to test locally. I haven't found the time to work out what was causing this issue so thanks for that. We should be catching that in config validation and presumably adding the trailing slash if it is missing. In fact, that would be the fix for this issue--to update the validation code.

IIRC, not providing a site_url can also result in sitemap.xml being generated with empty entries instead of the actual paths, but that's a different issue.

Yes, we are ware of the many issues with site_url not being defined. See this comment to #2189 where I provide a proposal for making site_url a required setting. Implementing that proposal includes updating the documentation.