Switch to another well maintained plugin from docsify

[canova]

Currently we use docsify for our user documentation. But it's not super well maintained. The last release was in 2023. There is a RC for version 5, but it's not released yet.

I think it's better to switched to a better maintained plugin for our user documentation.

┆Issue is synchronized with this Jira Task

[fatadel]

@canova shared https://vitepress.dev/, but there can be other options too

[mstange]

I think it would also make sense to host the docs at a different origin, e.g. profiler-docs.firefox.com . And maybe even put them in a separate repo.

I've had good experiences with SvelteKit as a static site generator but I don't have an opinion on the actual technology.

The only thing I would like to ask for is to have better URLs than we do at the moment. Currently we put the page in the hash. And when we scroll to an anchor, the scrolling happens with JS and there's a question mark in the hash. E.g. https://profiler.firefox.com/docs/#/./guide-startup-shutdown?id=firefox-for-android

[canova]

Yeah, I think VitePress is one of the nice alternatives. I haven't tried SvelteKit for docs, but it might be worth to try too.

One thing to note is that, with docsify, a build step wasn't required for the docs. It seems like all the other generators usually require one. But I think this is completely fine to add. And that's probably one of the reasons why the url wasn't good and had to be handled by JS.

I think I would prefer to keep the documentation in this repo. It's easier to change code and documentation at the same time if necessary. But I don't feel very strongly. Don't have a huge preference on the origin too. @mstange do you have a reason why putting it to a different origin is better? (well, I guess an attack surface is a good reason :))

[mstange]

Reduced attack surface is the main reason, yes. It would also let us deploy the docs from the main branch instead of from production (if that's something we want) and it would ensure by construction that the docs images don't end up in the service worker cache.