feat: URLs with no index.html suffix

[jhult]

Fixes #1251

[output.html]
no-html-extension=true

**no-html-extension:** When set to `true`, generates clean URLs without `.html` extensions. All pages are written to directory-based paths (e.g., `chapter/index.html` instead of `chapter.html`).

Special pages are placed in `_print/`, `_toc/`, and `_404/` directories.

All internal links use trailing-slash format (`chapter/` instead of `chapter.html`).

Works with all major static hosting providers (GitHub Pages, Netlify, Cloudflare Pages) and the built-in `mdbook serve` command.

**Note:** Chapter paths starting with `_print`, `_toc`, or `_404` will cause a build error.

Defaults to `false`.

Vaguely related PRs: #2570, #2993, #3028, #3034, #3038

[bens-schreiber]

Certainly fixes my issue #3028 . Would love to get this in.

[jhult]

@ehuss or @Dylan-DPC, I think many people would appreciate this being merged. I'd love any feedback you have to share.

[CattoYT]

Just had to hop into the discussion and say that this fixed my issue with cloudflare pages

Before: https://ad2d70e6.csbook-a6u.pages.dev/
After: https://215b27f3.csbook-a6u.pages.dev/

Thanks for your work <3

[rustbot]

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[jonathanpallant]

If I've read this right, the no-html-extension property doesn't remove the .html extension from the output files. Instead, it names file foobar/index.html instead of foobar.html, which most web servers will serve as /foobar/.

So, I wonder if the property needs a better name, to avoid confusing people who will see files on disk that still have a .html extension?

[jhult]

@jonathanpallant - this is true. I'm open to suggestions for a better name if you have one.

[szabgab]

It seems they are called Clean URLS so the option could be clean_urls

However, toc.html was replaced by _toc. Same with print.html. Why is the _ necessary?

[jhult]

All URLs are "clean" including toc, print, and 404. The question is, what do we call them? If we use toc, then no chapter can be named that. Thus, the appended underscore. However, I'm open to suggestions on how to better name these.

[szabgab]

Oh, I though the question was how to call the option that controls this behavior. For that I suggested clean_urls.

[jhult]

I'm open to clean_urls / clean-urls as the overall enablement for this feature.

My other question is what should we do with toc, print, and 404. Should we prefix them with an underscore? Whatever URL we use, no chapter can be named the same. Thus, my reason for prefixing them with an underscore. However, I'm open to suggestions on how to better name these 3 pages.

[szabgab]

Regarding the toc, print, and 404` pages, I am trying to understand what is the difference in behavior in the clean url version?

So I checked what happens now: (mdbook v0.5.2)

If I create a file called src/404.md it will replace the default 404 page. this is documented.

If I create a file called src/print.md its content is included in the searchindex file and the build process will fail with an error print.md is reserved for internal use

If I create a file called src/toc.md it will replace the toc bar for people using no JavaScript, but otherwise will have no impact. I don't think this is documented.

So I think we should keep the names without the _ but in a separate PR we should also at lest document the feature / bug. (We might even want to forbid the creation of toc.md and print.md, unless there is a value in them that I could not understand.

ps. Sorry for making two unrelated comments in one message earlier.

[jonathanpallant]

So I've thought about this a bit, and I don't love how it's going to fundamentally change the on-disk structures of my rendered book. I have a lot of old copies of the book, and it seems useful that the changes between versions are all currently relatively small.

For my specific issue, #2993 is a much less invasive fix. Perhaps we can just do both - then I get a free choice about whether to enable this option or not?

[jhult]

I didn't write the other PRs, but am not opposed to having both. Options can be nice.