Probably the number 1 and most notable issue we receive as feedback from the community.

The upgrade page in the docs site (source) is currently generated from UPGRADE.rst in the root of the repository.

mdbook expects markdown instead of RST, and thus the page looks a bit broken. We could convert UPGRADE.rst to a markdown file, though that would break existing links to the file (and this file is linked to quite frequently).

Possible solutions I can think of:

1. Don't import UPGRADE.rst into a mdbook page and instead simply link to the page on GitHub. This is probably the easiest solution.
2. Convert UPGRADE.rst to docs/UPGRADE.md, and leave UPGRADE.rst in place with a link to the docs website. Also quite a simple solution, although anyone who's linked to a specific header on UPGRADE.rst will have a bad time.
3. Use a mdbook preprocessor to convert RST to markdown while building the book.
   • Preprocessors can essentially modify the contents of a page during book rendering. I haven't seen one for RST -> MD yet though.

Thoughts?