404 page does not work outside the site root

[coyoteecd]

Since at the moment there is no localization support, we are using separate mkdocs projects per language, and each of these is generating their own 404.html page next to index.html. The end result is that index.html and 404.html is not served from the website root anymore.

While index.html has no issues since it uses paths relative to the current location, 404.html seems to use paths relative to root, making them basically useless. The layout is broken because assets cannot be loaded, and trying to navigate the docs from the served 404.html does not work either.

Excerpt from index.html (good):

<link rel="stylesheet" href="assets/stylesheets/main.a676eddb.min.css">

Equivalent from 404.html (bad):

<link rel="stylesheet" href="/assets/stylesheets/main.a676eddb.min.css">

Edit:
Using links relative to current page does not work either, because the non-existing URL may be https://website/docs/missingpath/missingsubpath (and 404.html is placed under docs). I think the fix here is to be able to be able to make mkdocs aware of the subdir where it is going to be hosted from, something which has been proposed and rejected before.

[waylan]

What is your site_url set to? By including the subdirectory in the site_url, you make MkDocs aware of it and the 404.html links are adjusted accordingly. In #2189 we are looking at making site_url a required setting to avoid this issue in the future.

[coyoteecd]

It's empty (intentionally). I have just played with it and it generates what I want, but then it also puts the absolute URL in a few places such as the logo, which is the reason we chose not to use it in the past.

Is there a way to get the behavior of site_url, but use root-relative URLs everywhere?

[waylan]

The entire url system within MkDocs is carefully crafted so that you can use a built site anywhere. The only change you need to make is to adjust the site_url and rebuild. That said, MkDocs builds a self-contained site. It assumes everything is within the URL of site_url.

If you want to break out of that mold, then you need to do some customizations of your own. At a minimum that would involve using the theme custom_dir and overriding template blocks. That would allow you to define the site_url, but not have it included on your pages.

As I said, we are moving to making site_url required, so the above-mentioned customizations would be required to avoid the site_url being included in the future. I should note that we are making this change because the single biggest cause of bug reports is users failing to set the site_url. Your case is unique as it is the first time anyone has suggested that they intentionally did not want the setting to be set.

Therefore, we are not going to add a new setting. We don't need two settings which contain the same information and we don't have a large number of users requesting the option to differentiate between the information conveyed (site is or is not in a subdomain) and the inclusion of the URL in the site. That said, if a third-party theme wanted to add a setting to the theme domain (perhaps something like theme.display_site_url), then they could. However, for the builtin themes, which provide the basic default functionality only, we will not be making such an addition.

So you have two options: do your own theme customizations or explore third party themes which may offer additional functionality/flexibility.

[coyoteecd]

I should note that we are making this change because the single biggest cause of bug reports is users failing to set the site_url. Your case is unique as it is the first time anyone has suggested that they intentionally did not want the setting to be set.

Well setting the site_url requires knowing in advance the domain name where the doc site will be deployed. So we skipped it thinking it's optional (and I agree with your comments in the other issues, if mkdocs does not work well without it, then make it mandatory to save the pain of discovering that later).

Out of curiosity, is there a particular reason it's putting the absolute URL in those few places? I can see the rest of the page links use root-relative paths when I enter a site_url (including the 404 page). So why do we include the domain name just in the logo and footer?

Reason I ask is, well, it's a bit weird. My Angular SPA does not need to know in advance where I will host it... so I expect other people will find it weird as well, and maybe this reasoning should be documented here. Could be that the answer is already hidden in one of the github issues/PRs and I just couldn't find it :(.

[waylan]

The reasoning for the current behavior is explained in detail in this comment. In short, MkDocs is a static site generator so the behaviors of dynamically generated sites don't apply.

[coyoteecd]

After digging a bit, I think I found the cause of my confusion.
The explanation you're giving was making sense, what I did not understand is why when filling in a site_url, the nav header uses it "as-is", so linking to https://example.com/project/ instead of e.g. /project/ as the rest of the page does.

But I think this is the fault of the mkdocs-material theme, which uses site_url for that link instead of base_url (?). Found it in the source here: https://github.com/squidfunk/mkdocs-material/blob/d6317dc51494309c7b09d4d80fa4611f1e6dc188/src/partials/nav.html. So I guess I should take this part to the correct repo then.

[coyoteecd]

Apparently it was just fixed by squidfunk/mkdocs-material#2388.
@waylan I am closing this, thanks for your patience in providing links to the github comments.