Mkdocs-material: Relative paths to assets must be used in 404.html

[Sharom]

Description

Absolute paths to assets are used in 404.html. It breaks rendering of this page when documentation located not at the root of the domain.

Expected behavior

Relative paths are expected to be used in 404.html for import of assets as for all other pages.

<link rel="stylesheet" href="./assets/stylesheets/application.8d40d89b.css">
<link rel="stylesheet" href="./assets/stylesheets/application-palette.6079476c.css">
...

Actual behavior

<link rel="stylesheet" href="/assets/stylesheets/application.8d40d89b.css">
<link rel="stylesheet" href="/assets/stylesheets/application-palette.6079476c.css">
...

Package versions

• Python: 2.7.14
• MkDocs: 0.17.3
• Material: 2.7.2

[squidfunk]

This is due to the fact that {{ base_url }} is not set correctly. @waylan – is Material using the template variables incorrectly or what are your thoughts on this, see

https://github.com/squidfunk/mkdocs-material/blob/a7b6b608c038c22d3d1d60dc5f5ec60cbf167a68/src/base.html#L100-L108

[waylan]

The problem is related to the fact that the error page is static. We don't generate the error page at the time of the request. The same error page needs to be used for requests to /foo/. /foo/bar/, and /foo/bar/baz/, however, the relative base_url would be ../, ../../, and ../../../ respectively for each of those requests. But we only generate a single error page that must work from any location. The only way to accomplish that is with absolute URLs. Therefore, when building the error pages, we use the value of site_url to set base_url to an absolute path from the server root. Any problems are likely related to the user not properly setting their site_url.

As an aside, when running the local server we override the value of site_url so that the error pages work correctly on the dev server. An unfortunate side-effect is that its becomes difficult to catch and/or test errors in the site_url config value with the dev server.

A more detailed explanation can be found in this comment to mkdocs/mkdocs#77. Also see mkdocs/mkdocs#1318 for details regarding the dev server.

[Sharom]

We don't generate the error page at the time of the request. The same error page needs to be used for requests to /foo/. /foo/bar/, and /foo/bar/baz/...

You are right, I have overlooked this.

[Sharom]

So, it looks like we can close the issue.

[waylan]

@Sharom just curious if you were able to resolve the issue by adjusting the value set for the site_url config setting?

[squidfunk]

Thanks for the thorough explanation @waylan! Closing this as answered.

[Sharom]

@Sharom just curious if you were able to resolve the issue by adjusting the value set for the site_url config setting?

@waylan Yes, it solves the issue.

Just for example:

site_url: https://example.com/docs

Generates:

<link rel="stylesheet" href="/docs/assets/stylesheets/application.8d40d89b.css">
<link rel="stylesheet" href="/docs/assets/stylesheets/application-palette.6079476c.css">
...

[Radiergummi]

@squidfunk I've just found this issue with the opposite problem: My site is running on the domain root, but assets wouldn't be resolved for any nested pages. Looking through the comments, I noticed my site_url has no trailing slash, which means base_url will resolve to ''.
Would it make sense to append that pesky slash if missing (as in, baseUrl.endsWith('/') ? '' : '/')? It's a subtle bug and I think it isn't mentioned in the docs to be necessary for 404s.

[squidfunk]

Is it really mentioned in the docs or part of the default MkDocs theme?

[RDIL]

Still an issue

[Stanzilla]

@squidfunk for me the error is coming from main.js when it tries to create a new searchWorker var searchWorker = new Worker(joinUrl(base_url, "search/worker.js")); which happens when you develop a custom theme based on material but don't include

# Don't include MkDocs' JavaScript
  include_search_page: false
  search_index_only: true

in your mkdocs.yml

[squidfunk]

I can’t provide support for customizations, sorry

[Stanzilla]

Was more of a notice and "if you find this issue via Google, here is what it could be" thing for other people :)

[jagguli]

still an issue

path never gets prepended with /

    {% block styles %}
      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.fe0cca5b.min.css' | url }}">
      {% if palette.scheme or palette.primary or palette.accent %}
        <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.a46bcfb3.min.css' | url }}">
      {% endif %}