Modifying generated document paths to exclude extensions

[and3rson]

Let's say I have the following HTML files generated by Sphinx:

• /index.html
• /manual/index.html
• /manual/building.html
• /manual/deploying.html
• /reference/index.html
• /reference/api.html
• /reference/plugins.html

Obviously, they are accessed and cross-referenced by their cannonical URL which includes HTML file path (FYI - I'm hosting them on readthedocs).

However, I'm wondering if it's possible to exclude ".html" from each file to have those docs accessible by the following URLs:

• / (already works since it contains index.html)
• /manual (ditto)
• /manual/building
• /manual/deploying
• /reference (ditto)
• /reference/api
• /reference/plugins

Somehow this format looks less bloated to me. I understand .html extension in URL makes it more "cannonical" in terms of SEO, but just for the sake of readability I'd like to have Sphinx generate such output.

My naive (and probably the most portable) approach is to render each RST file as a folder with index.html inside. For example, /manual/deploying.rst can be rendered as /manual/deploying/index.html, and thus can be accessed as http://docs.example.org/manual/deploying.

I have 2 questions:

• Is there a nice way to modify the logic of how Sphinx generates target filename for HTML outputs?
• Once this is done, is there a way to make Sphinx reference those documents by their folder (so that :doc:`/manual/deploying` resolves to /manual/deploying instead of /manual/deploying/index.html?

Thanks in advance! Any thoughts and suggestions are welcome.

[jdillard]

I think you want to try using the dirhtml builder: https://www.sphinx-doc.org/en/master/usage/builders/index.html

[and3rson]

Amazing! No idea how that slipped past me. Thanks!