Document how to specify URL redirects

[SamLau95]

Is your feature request related to a problem? Please describe.

I have a book with URLs like: https://www.textbook.ds100.org/ch/10/modeling_intro.html . Notice that the chapter number is in the URL itself. I want to insert a new chapter in between ch06 and ch07 and renumber the later chapters. For instance, the URL above will become https://www.textbook.ds100.org/ch/11/modeling_intro.html .

However, this will break old links to book pages.

Describe the solution you'd like

I'd like a way of redirecting users between URLs in the book. In this example, I'd redirect users from https://www.textbook.ds100.org/ch/10/modeling_intro.html to https://www.textbook.ds100.org/ch/11/modeling_intro.html . Maybe something in the config or TOC that looks like:

- redirects:
  - from: ch/10/modeling_intro
    to: ch/11/modeling_intro

Or, maybe it's something we add to individual TOC entries, like:

- file: ch/11/modeling_intro
  old_urls:
    - ch/10/modeling_intro

Describe alternatives you've considered

One alternative is to manually add a modeling_intro file into ch10 that gives the user a link to the right page in ch11. This isn't preferable for me since in my case this would involve adding 50 or so extra files to the book just for redirecting users around.

[chrisjsewell]

Hey @SamLau95 note in our docs here we use https://github.com/wpilibsuite/sphinxext-rediraffe to achieve exactly this 😄: https://github.com/executablebooks/jupyter-book/blob/980c99767aa03a7840ec58567ceaa49b27bd2400/docs/_config.yml#L84-L91.

So I would say this is the recommended method. Perhaps we should note that somewhere in the documentation

[choldgraf]

@chrisjsewell yeah we should add this to the advanced sphinx config docs 👍

[SamLau95]

Thanks for this! It would also be nice to have a page in the docs with potentially useful Sphinx extensions since I'm not familiar with the ecosystem (and Sphinx extensions tend to be focused on code documentation rather than book-like content).

[Remi-Gau]

FYI it you want to redirect to external pages it may be better to use: https://documatt.com/sphinx-reredirects/install.html

[minrk]

how do redirects work in jupyter-book 2 now that we don't have rediraffe available?