Proposal: use vitepress to generate documentation site

[marcalexiei]

Recently I found out that all vite ecosystem docs are powered by vitepress.
Here is the official site: https://vitepress.dev

Even if it is not released yet, it's on rc status right now, it looks pretty good looking and solid to me.

Another library that relies on vitepress for docs is husky: https://typicode.github.io/husky/

---

Some of the features that might benefit the docs are:

• code groups: we can use tabs to show different command based on OS or package manager.
• alert variants: right now there aren't many variants available

You can see more examples here: https://vitepress.dev/guide/markdown

docsify doesn't offer such features by default, you have to include additional scripts.

Since we are migrating to vitest on #3850 I think that having documentation powered by the same ecosystem
could be a good benefit.

---

What do you thing about it?
If you agree I'm more than willing to setup a PR!
Before proceeding I will wait merge of #3850 to avoid conflicts

[JounQin]

I would recommend to use https://rspress.dev

[marcalexiei]

I quickly tried rspress in another branch and here are my thoughts:

Pros

1. rspress is more mature.
2. rspressincludes more plugins by default, like tabs, which are not included by default with vitepress.
3. rspress is incredibly faster and has a better dev experience
   E.g: HMR is way more efficient than vitepress.

Cons

rspress has a lot of dependencies.
I assume it is the same for vitepress but it shares them with vitest.

To give an idea, here are the addition and deletion on yarn.lock:

• rspress - 3104 insertions, 92 deletions
• VitePress + vitepress-plugin-tabs - 499 insertions, 1 deletion

---

I'm not an expert of both tools so I don't have a preference since the configuration is quite similar.
Besides that, what I've done so far with vitest can be easily migrate to rspress.

@escapedcat what do you think?

[JounQin]

The biggest downside of vitepress(or vite actually) is the different behavior between development vs production.

[marcalexiei]

Gotcha,
I will close this issue and the associated PR to recreate new ones with updated information this weekend.

thanks for the info @JounQin!

---

@escapedcat is this good for you?

[escapedcat]

Hm, so looking at both projects it looks like that vitepress is much more popular and has a bigger community of users (i.e. "Used by 141" vs. "Used by 20.2k") and devs. I tend to chose these projects over something that is somewhat better in a certain context.

The biggest downside of vitepress(or vite actually) is the different behavior between development vs production.

Can you elaborate? Is this relevant for commitlint? Currently we use a very old docs-system (I believe). We never cared about dev Vs. prod for docs and I don't think we will.

There not urgent need to migrate to something new. So if we migrate I'd rather chose something proven which will last for the next ~5 years or so like the current one does :P
I have seen too many new projects fail after some years so I'm rather sceptical with choosing the hip/new/optimized one.

Hope this makes sense. Happy for feedback.

[marcalexiei]

There not urgent need to migrate to something new.

Due to ESM migration I think that would be great to ship it with a new documentation.
Also since we are not using advanced features that requires React or Vue components.
I don't see problem in switching to another generator in the future.

In conclusion I'm more than willing to migrate to vitepress right now 😀.
I started yesterday and it was fun, so I would like to complete the migration!

[JounQin]

Can you elaborate? Is this relevant for commitlint?

Oh, sorry for the confusion, I was talking about a common issue instead of commitlint specific one.

I don't know if we're using some advanced features of like React/Vue components right now and in the future.

Although rspress is not popular as vitepress yet, but personally rspack is a better build tool approach then vite considering the root issues I mentioned above and

troll http requests for importing a single dependency, etc, for example

But of course, for simple document usage, vitepress is also suitable.

[escapedcat]

Cool, let's move on with vitepress then :)
@marcalexiei let me know if I can help with converting things

[marcalexiei]

Done via #3921