Facilitate maintaining URLs with redirect mapping

[behnam]

Most of the books being authored by mdBook are live documentations of projects under development, meaning that they require constant updates to the content and addition and removal of sections and chapters. Besides updating content to some URL or adding new URLs, all other kinds of maintenance/update changes result in broken URLs, which is not optimal for these projects, from a being reference documentation point of view. Because of that, IMHO it's needed to facilitate keeping URLs alive by having a simple way to redirect old URLs to new ones.

A simple solution that should cover majority of these cases is to have a redirect-map file, having the old path as the first field, and new path as the second. During build, HTML files with redirect head meta tags are created for the old paths, redirecting user to the new path. In practice, this file would only grow and there would never be deletions from the file. Also, a warning or error will be raised if a file path matches a redirect path, preventing conflicts between content and redirect URLs.

What do you think?

[azerupi]

I think this a very good idea! I would put it behind an opt-in option in the book.toml file, because not everyone needs it. But it would just be a one time option to enable.

Do you envision this file to be maintained manually? I suppose, because it would be hard to know which urls need to map to what file. Anchors should probably be out of scope for a first version.

[behnam]

Yeah, maintaining the list manually would make the feature implementation much easier and keep the build system stateless (not depending on previous builds). From user perspective, I think it's fine as long as we set up warnings/errors for overlapping paths.

So, the option in book.toml would take a path to the map file, to be used like redirect_map = REDIRECTS?

Also, an additional features we can consider: support full URLs as redirect destination, for cases a page/content moves outside of the current book.

[azerupi]

So, the option in book.toml would take a path to the map file, to be used like redirect_map = REDIRECTS?

Yes, something along those lines. I think it would make sense to put it under the [output.html] table, because it is pretty specific to html versions of the book. In TOML I also prefer dashes instead of underscores. So it would be something like:

[output.html]
redirect-map = "REDIRECTS"

For the file itself, do you have a format in mind?
I was thinking about having something simple to parse, maybe lines with old_url = new_url. I'm open to other suggestions :)

support full URLs as redirect destination, for cases a page/content moves outside of the current book.

👍

[behnam]

Well, if we want to have a more formatted file, I don't see any reason not to put it in book.toml to start with. How about this?

[output.html.redirect]
"some-chapter/some-page.html" = "another-chapter/some-page.html"
"some-chapter/another-page.html" = "https://some-site.book/another-page.html"

# and, optionally, if more fields are needed in the future...
"some-chapter/yet-another-page.html" = { target = "...", title = "...", ... }

[azerupi]

That is a pretty good idea!
We can support that format and also support taking a path:

[output.html]
redirect = "redirect.toml"

For when it becomes a bit unwieldy to keep it in the book.toml file.