mkdocs: Use use_directory_urls: false breaks on empty site_url

May I ask why you need the complete url of the website to build the documentation website?

If I could do

site_url: /

I could upload the same build on different hosts if it was possible.

The current error I get when I have this error logged:

ERROR   -  Config value: 'site_url'. Error: The URL isn't valid, it should include the http:// (scheme)

NB: I ask about this here because it’s the issue where it was discussed to make site_url mandatory when use_directory_urls is true

Is there a way to set the site_url with the command line?

In the 1.2 release (which will require a site_url) the easiest way to do this would be through an environment variable, which is another new feature of 1.2. See more here.

First, use the !ENV tag in the config file:

site_url: !ENV [SITE_URL, https://fallback.com]

Then on the commandline do:

SITE_URL="https://example.com" mkdocs build

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 https://github.com/squidfunk/mkdocs-material/commit/454339bd359b8708aaf1b2cfb22098b158d475d3 – just in case you’re using this template. Other than that, the commit may be helpful for other theme devs.

@MathieuPuech Thanks for the suggestion https://github.com/mkdocs/mkdocs/issues/2189#issuecomment-847816816 In https://github.com/mkdocs/mkdocs/pull/2503 I want allow specifying just the path, not the whole URL. Of course, site_url will stop being mandatory anyway, so you probably don’t care so much about that ability anymore, but it gave me an idea 😃

I don’t feel I’m proficient enough in the internal mechanics of MkDocs to decide whether that covers all cases, but it sounds good to me in general. In essence, we have three cases that should be covered:

• Web hosting with directory URLs: site_url set and use_directory_urls: true (default)
• Web hosting without directory URLs: site_url set and use_directory_urls: false
• Local serving: site_url not set and use_directory_urls: true (must be)

However, there might be cases where people don’t set the site_url and use use_directory_urls: true, e.g. when they want to deploy the same documentation on different domains. As I understood, you’d want to issue a warning then, making it impossible to build with --strict. I’d expect some issues rolling in for those cases, as it was the case for #2108.