Use use_directory_urls: false breaks on empty site_url

[ktomk]

When setting the site_url to null (default) and use_directory_urls is false to make the docs browse-able in a user friendly fashion accessible from the local file-system, in the default mkdocs theme the link to the site on the site-name:

<a class="navbar-brand" href=".">{{site_name}}</a>

is missing the /index.html added to the existing href . (dot).

[ktomk]

The HMTL fragment in the report is from base.html, the href value from nav.homepage.url:

mkdocs/mkdocs/themes/mkdocs/base.html

Line 66 in ff0b726

<a class="navbar-brand" href="{{ nav.homepage.url|url }}">{{ config.site_name }}</a>

With best intentions, I think this could be fixed in the url filter:

• Given mkdocs is configured to not use directory urls
• When the url filter is applied and the url filter is about to return an url-text having the first and the last character Unicode Character 'FULL STOP' (U+002E)
• Then url-text is appended with /index.html before the url filter returns the url-text.

[squidfunk]

This is indeed a bug of MkDocs which should be fixed. We also had this problem as part of Material for MkDocs, which I was able to mitigated with squidfunk/mkdocs-material@454339b – just in case you're using this template. Other than that, the commit may be helpful for other theme devs.

[waylan]

Given the reliance on site_url for some basic functionality, I'm wondering if the config option should be required. I have seen a lot of reports over the years which have all been resolved simply be setting a site_url. If we required it, then users wouldn't miss it. Thoughts?

[squidfunk]

Wouldn't that break local browsing? Some users of Material for MkDocs build their docs and distribute the resulting *.html files as part of their software.

It's great to see you're back, @waylan!

[waylan]

Wouldn't that break local browsing?

That is a potential concern; except that we have never officially supported local file browsing. For the serve command, we override the setting using the dev_addr. But that doesn't work for local file browsing. Would setting the value to file:// work? If so, that might be a way for users to specifically indicate that they want local file browsing and we could (possibly) alter some behaviors based on that (like perhaps change the default value of use_directory_urls). Yes, that means we could potentially add official support for local file browsing.

I should note that any of the existing solutions for local file browsing are hacks by users. While I don't see a need to break those hacks unnecessarily, any new official way to support such a feature is not likely to work well with the existing hacks.

Finally, the elephant in the room is the builtin search plugin, which does not work with local file browsing and the primary reason why we do not officially support the option. IIRC, the Material theme doesn't have that limitation, but we would need to address that before any official support exists. That said, any changes to the plugin should be discussed in a separate issue. At a minimum, if site_url is set to file:// we might disable the default plugin and require the user to explicitly include a search plugin in their config. In that way, we ensure the user is responsible for providing a working search feature when using local file browsing.

All of the above are just ideas. I havn't looked at the feasibility of any of them. I'm just thinking out load here.

[waylan]

we could (possibly) alter some behaviors based on that (like perhaps change the default value of use_directory_urls)

That got me thinking... What if we just changed the default of use_directory_urls when site_url is blank? As previously mentioned, the serve command overrides the setting using the dev_addr. But with the build command, site_url remains blank if it is not configured. Without a site_url we could assume the files will not be hosted behind a server. In that case, the default for use_directory_urls should be False. In that way, we can only get a conflict between the two options if the user explicitly sets them in conflict. And we can warn against that in documentation.

The one concern here is that there is a distinct difference in output between serve and build simply by failing to set one optional config option. That's why I keep thinking that the site_url option should be required.

[squidfunk]

Finally, the elephant in the room is the builtin search plugin, which does not work with local file browsing and the primary reason why we do not officially support the option. IIRC, the Material theme doesn't have that limitation, but we would need to address that before any official support exists. That said, any changes to the plugin should be discussed in a separate issue. At a minimum, if site_url is set to file:// we might disable the default plugin and require the user to explicitly include a search plugin in their config. In that way, we ensure the user is responsible for providing a working search feature when using local file browsing.

Material relies on mkdocs-localsearch and iframe-worker to support search on file://. A lot of work was put into getting this to work, so it would be quite sad if we'll loose support for local browsing and search. Adding support for local search to the default themes should also be possible with some small additions.

That got me thinking... What if we just changed the default of use_directory_urls when site_url is blank? As previously mentioned, the serve command overrides the setting using the dev_addr. But with the build command, site_url remains blank if it is not configured. Without a site_url we could assume the files will not be hosted behind a server. In that case, the default for use_directory_urls should be False. In that way, we can only get a conflict between the two options if the user explicitly sets them in conflict. And we can warn against that in documentation.

Hard to say whether that won't break anything. It's only another default, so it can be overridden, but it may result in confusion for users.

I'd like to get @wilhelmer in the loop because he's the own maintaining the localsearch plugin.

Another idea:

site_url: null

[waylan]

Material relies on mkdocs-localsearch and iframe-worker to support search on file://.

I just looked at those for the first time. At a glance, I don't see any reason why that wouldn't work with other themes with a couple minor tweeks. Still, it seems like a lot of work for the user (overriding template blocks) just to enable local file browsing. I wonder if perhaps mkdocs-localsearch could be merged with the search plugin. In fact, before looking at it, I assumed it would be a replacement for the search plugin, not an additional plugin which works beside it. In any event, that is a discussion for a different issue.

So far we have three proposed values for site_url: file://, null and an empty string. The issue with the empty string is that that has been the default for some time. We could change the default behavior in surprising ways for some users who have previously carefully crafted a config in just they way they want. Introducing null provides us a way to introduce a new behavior which won't break any existing configs.

I also have some reservations about file://. Presumably site_url would point at the site root. But for file based browsing, the site root is not the same as the system root. In that case, the value would need to be file:///path/to/site/root and that value could change based upon where within the file system a user happens to have copied the files. Using null avoids that issue.

[squidfunk]

In order for search to work locally, the search_index.json is served as search_index.js, which exposes the search_index in window scope. The mechanics are entirely different from the normal way this would be done, as XHR is not available. It could be integrated with the search plugin, sure. That would actually be absolutely amazing, but I think it won't work without explicit theme support, as the search_index.js would need to be included by the theme before the application logic. As this is now a blocking request, performance would degrade for non-local environments, as search_index.js is not loaded asynchronously but is part of the critical rendering path.

Furthermore, if search is implemented as part of a web worker, the iframe-worker polyfill is necessary, too, increasing the payload size even more, albeit it's <1kb gzipped.