404 rendering fails

[CCFenner]

I have an issue with the 404 page, that is not rendering correct. I see several issues in the browsers error tab. I use GH action to deploy the page to GH pages on an GH Enterprise instance.

The error page fails to load several file from this URL: e.g

https://github.<host>/<pageName>/assets/stylesheets/main.8c3ca2c6.min.css

On other pages this URL is used:

https://github.<host>/pages/<org>/<repository>/assets/stylesheets/main.8c3ca2c6.min.css

I tried fixing this by setting the site_url to different values but without success.

• site_url: https://github.<host>/pages/<org>/<repository>
• site_url: https://github.<host>/pages/<org>/<repository>/
• site_url: https://<customUrl>
• site_url: https://<customUrl>/

Using mkdocs serve locally there are no issues:

http://127.0.0.1:8000/<pageName>/assets/stylesheets/main.8c3ca2c6.min.css

Any idea?

[squidfunk]

The site_url must be set to the canonical location where your documentation lives, as assets are referenced absolutely for 404 pages. Thus, if http://127.0.0.1:8000/<pageName>/assets/stylesheets/main.8c3ca2c6.min.css works, it must be:

http://example.com/<pageName>/

[squidfunk]

Yes, but I'm not sure how I can help you besides what I already mentioned 🤷‍♂️

[kamilkrzyskow]

The 404.html static template doesn't use the site_url as-is, but only the part for the path to create the absolute URL.

For example GMC has the https://gothic-modding-community.github.io/gmc/ site_url and absolute path in the 404 page only uses the /gmc/ prefix:

• https://gothic-modding-community.github.io/gmc/404.html
• <link rel=stylesheet href=/gmc/assets/stylesheets/main.f2e4d321.min.css>

So assuming I would use the GitHub Enterprise with those 2 links from the OP and /gmc/ it would always result in:

• https://github.<host>/gmc/assets/stylesheets/main.8c3ca2c6.min.css

I don't know how it's being deployed, but I'm assuming you deploy the site "once" and it's available at different URLs at the same time.
So you need to somehow support 2 prefix paths or more:

• /<pageName>/
• /pages/<org>/<repository>/pr-preview/pr-712/

The only idea I have currently would be to use a hook during the build process to modify the 404.html in on_post_build event to allow those different pages to access some direct URL to the assets instead of resolving it with the base / absolute path.

So instead of:

• <link rel=stylesheet href=/gmc/assets/stylesheets/main.f2e4d321.min.css>

I would have

• <link rel=stylesheet href=https://github.<host>/<SomeStaticPart>/assets/stylesheets/main.f2e4d321.min.css>

EDIT: However, in general all paths are relative to some "base" path and if the base keeps changing, many other things like the search or social cards might break along the way 🤔

[CCFenner]

Sorry, the pr-preview/pr-712/ sneaked in. It's from pr-preview action.

[CCFenner]

Maybe another hint.. the 404 page load fine, no issue.

OK

https://github.<host>/pages/<org>/<repository>/404.html

Fails

https://github.<host>/pages/<org>/<repository>/4040.html
https://github.<host>/pages/<org>/<repository>/4/04.html

But loading anything else that should point to 404 does not show correctly.

Where is the routing done?

[kamilkrzyskow]

Check inside the Browser Web Dev tools to see what link is being loaded, and compere them between the working and not working sites. If the 404.html loads the files properly, then I guess the issue is on the GitHub Enterprise end, as in, it doesn't load the correct 404.html file when a 404 error occurs, but instead loads something else, like the index.html. You can diff compare the source HTML of the 404.html and the "404 page" to see what page is being loaded.

The "routing" is generated for each page during MkDocs build, via the template url filter, and stays static for each .html file, and later GitHub Pages / GitHub Enterprise decides what html file to load when 404 error occurs.

mkdocs-material/src/templates/base.html

Lines 102 to 110 in 790b0e8

	<link rel="stylesheet" href="{{ 'assets/stylesheets/main.css' | url }}" />
	<!-- Extra color palette -->
	{% if config.theme.palette %}
	{% set palette = config.theme.palette %}
	<link
	rel="stylesheet"
	href="{{ 'assets/stylesheets/palette.css' | url }}"
	/>

URL filter:

• https://github.com/mkdocs/mkdocs/blob/bb7e8b62185b11d9f59bb7f50b13c15134f62f8a/mkdocs/utils/templates.py#L37-L40

URL normalization:

• https://github.com/mkdocs/mkdocs/blob/bb7e8b62185b11d9f59bb7f50b13c15134f62f8a/mkdocs/utils/__init__.py#L205-L216

Different base_url for templates like the 404.html:

• https://github.com/mkdocs/mkdocs/blob/bb7e8b62185b11d9f59bb7f50b13c15134f62f8a/mkdocs/commands/build.py#L68-L76

[CCFenner]

In the end it was an issue with my testing setup. I adjusted the site_url in a PR and had that deployed to gh-pages (in a subfolder with https://github.com/rossjrw/pr-preview-action), but the site_url of the productive deployment was still wrong. That lead to the invalid 404 page resolution.

[squidfunk]

Thanks for reporting this back! It might be valuable to others running into the same troubles ☺️