What about transforming our documentation to a readthedocs-like one?
I didn't like rst a lot at first sight but it has very interesting features.
- Include the content of files.
This is amazing to create up-to-date and CI-proof tutorials.
- Clear navigation between parts.
Current architecture is okay, but moving from one file to another is hard.
Is is also quite easy to miss a documentation part with current markdown doc.