Some doc links lead to a broken page depending on wether they end with .html or /

[Zylann]

Details

• Read the Docs project URL: https://readthedocs.org/projects/voxel-tools/
• Read the Docs username (if applicable): Zylann

Expected Result & Actual Result

I have links to my documentation such as this one, which works:
https://voxel-tools.readthedocs.io/en/latest/

I think the following one used to work, but recently it leads to a broken page with no CSS:
https://voxel-tools.readthedocs.io/en/latest/quick_start/

However, if I replace the / with a .html, the page is no longer broken:
https://voxel-tools.readthedocs.io/en/latest/quick_start.html

There is indeed a difference between the first link and the two other ones since the first one does not specifically point to a page so it's probably handled differently. However, I did not invent or manually type the other original page links, so something likely changed recently. Is this intented? Should I be using only links ending with .html now?

[humitos]

However, I did not invent or manually type the other original page links, so something likely changed recently. Is this intented?

I'm not aware that something related to this has changed in the last weeks. cc @stsewd @ericholscher

Should I be using only links ending with .html now?

I'd say that you should always use the link with .html if you are using "Sphinx HTML" builder. If you want /quick_start/ to redirect to /qick_start.html you should use the redirect "Sphinx HTMLDir -> HTML". See https://docs.readthedocs.io/en/stable/user-defined-redirects.html#sphinx-redirects

[Zylann]

I'd say that you should always use the link with .html if you are using "Sphinx HTML" builder.

I use MkDoc

[stsewd]

@Zylann hi, this looks like a change in the latest mkdocs release, you can see these warnings in your builds https://readthedocs.org/projects/voxel-tools/builds/13998765/

Warning: This option is now required. Set to a valid URL or an empty string to avoid an error in a future release.
Config value: 'site_url'. Warning: The 'use_directory_urls' option has been disabled because 'site_url' contains an empty value. Either define a valid URL for 'site_url' or set 'use_directory_urls' to False.

You need to set site_url in your configuration or pin the mkdocs version to a previous release https://github.com/Zylann/godot_voxel/blob/master/doc/requirements.txt

[Zylann]

So that means I need to do this?

site_url: https://voxel-tools.readthedocs.io/en/latest/

Or is there a part of this URL I need to truncate?
The issue I'm suspecting here is that readthedocs provides multiple base URLs for doc versions (and apparently language), so putting the above in site_url doesn't seem correct. Alternatively, is it something readthedocs could set during deployment, as the docs seem to imply?

[stsewd]

So that means I need to do this?

yes, using site_url: https://voxel-tools.readthedocs.io/en/latest/ should do it.

The issue I'm suspecting here is that readthedocs provides multiple base URLs for doc versions (and apparently language), so putting the above in site_url doesn't seem correct

I'm not sure if mkdocs will use that url in all links or just to set some other things, but you are right, that would change on each version, I think mkdocs allows using env vars now https://www.mkdocs.org/user-guide/configuration/#environment-variables, we exposer some env vars that could be useful https://docs.readthedocs.io/en/stable/builds.html#build-environment.

Alternatively, is it something readthedocs could set during deployment, as the docs seem to imply?

We are moving away from overriding config values from the user.

[Zylann]

So indeed doing !ENV var would work, however I had a look at environment variables provided by readthedocs, and while the info is present, it is only available through separate variables. I would have to concatenate them with / in between, and that doesn't seem to be possible, from what I see on https://github.com/waylan/pyyaml-env-tag (this is the small library the Yaml parser of MkDocs uses to insert environment variables), unless I'm missing something obvious (given the syntax, I doubt something like https://!ENV READTHEDOCS_PROJECT.readthedocs.io/!ENV READTHEDOCS_LANGUAGE/!ENV READTHEDOCS_VERSION would work)

[stsewd]

I doubt something like https://!ENV READTHEDOCS_PROJECT.readthedocs.io/!ENV READTHEDOCS_LANGUAGE/!ENV READTHEDOCS_VERSION would work

Yeah, maybe we can expose an env var with the full url or could also request this as an improvement in mkdocs.

Opened #8260 to track that change.