Since the last big blocker for releasing rs.js 2.0 was the broken documentation setup for quite a while now, I embarked on a little journey last week and ended up with what I think is a pretty good improvement for both the main remoteStorage website as well as the rs.js documentation.
SphinxJS and especially its TypeDoc integration have not been properly maintained, since the project was abandoned by Mozilla. And regular changes in the ReadTheDocs build setup also required regular time investment on our part to make things work. I didn’t see a good way of fixing that situation, other than ripping out all the parts that kept breaking over time.
Then I ran into VitePress, and found out that there’s even a TypeDoc Markdown plugin for it. And since we already used Markdown for the main website, I thought why not combine all of it into one again.
So here’s what I have right now:
One nice aspect, among many benefits of this new setup, is that you can run a preview of only the rs.js documentation directly in the rs.js repo, without even checking out the website repo. And in the website repo, I added rs.js as a Git submodule, so you can either pull in rs.js docs changes or push them from there, too.
If you want to try it out for yourself, just npm install the dependencies in either repo (no --force required anymore), and then just run npm run docs:dev.
Other benefits:
- Everything is Markdown now, no RST anymore (even examples in the TypeDoc comments are Markdown)
- More independence from GitHub Pages tech again. We just deploy a static build and pull in the contributor list via a script before building. That also means no Jekyll/Ruby for local builds anymore.
- We can cross-link locally between the main website and the rs.js docs
- VitePress default theme niceties like dark mode, page content navigation/summary on the right side, etc.
- We can customize anything, pull in remote data, and add more interactive features with Vue components (see e.g. the Contributors component for that). Could even add real demos directly in the docs.
- Modern versions of TypeScript and TypeDoc fully supported, and we can use all their features. No dependency hell for that anymore
- …
Current status
Most of the work has already been done, including content updates and improvements. Left to do:
- Fully port all of the rs.js docs’ content
- Write a new contribution doc for the documentation/website itself
- Go over all pages and make sure all links are working, revise outdated content
- Add content to the new Design page on the main website, get rid of the legacy wiki folder/pages
- Add a GitHub Action for deploying the static build dir to GitHub pages
- Resize the images on the how-it-works pages (scale via CSS)
- Update image/asset handling in rs.js docs
- …
Hope you all like it! Would appreciate any feedback and other help I can get on this. 
