mkdocs
Clarify side effects of not setting `site_url`
Sitemap generated with empty loc tags, i.e.
<url>
<loc></loc>
<changefreq>daily</changefreq>
</url>
Example attached. sitemap.xml.gz
Effect
Causes Google Search to report errors, request correction and resubmission.
Version
☕ sjt@max:~/kx/code/v2$ mkdocs --version
mkdocs, version 1.0.4 from /usr/local/lib/python3.7/site-packages/mkdocs (Python 3.7)
Configuration
Do you have external links in your nav config? If so, then this is a duplicate of #1742, which was fixed in #1748 and will be available in the next release.
Sorry, but I'm not downloading random files from bug reports. You can include the relevant section of the config in a comment if you want to share it.
I saw a couple smart quotes in the nav listing - not sure if that could be relevant/responsible.
I found that if I do not have site_url defined in my yaml file then all of the <loc> tags are None. Do you have that set?
@brandongc lifesaver — we had this issue too and I never got around to debugging it. A bit harder to track down, cause it works fine with mkdocs serve (I bet there's an undocumented default value being injected)
@aeromusek you are correct. When using serve, the site_url setting is set to the value of dev_addr. This is necessary to avoid things breaking on the local server.
This seems to trip people up more than I expected. Perhaps we should make it a "required" setting as a number of things break without site_url defined. The problem with that is that requires a URL be defined immediately when a new project is just getting started. Sometimes its nice to play with things for a while before reaching the point where we think about the domain.
Either way, we probably should document this. And at the least do a better job of calling out the site_url setting as many new users are missing that this setting exists, let alone setting it.
Perhaps issuing a WARN or INFO on mkdocs build when site_url is not defined?
The behavior makes total sense and is quite elegant, once it's clear how things are working. Jekyll actually does exactly the same thing.
The confusing part for me was having (seemingly random) things like the sitemap break without any clear reason. At the least, I think it would be helpful to add some additional details here, including that this value is used for more than just the canonical metatag, and that it's really not optional for a production environment.
A WARN or INFO also would be helpful.
I've edited the title to keep this issue as open as a documentation issue: not setting site_url can have some side-effects as the one described here (empty sitemap when building but not when serving).
