search

dxos / dxos

TypeScript implementation of the DXOS protocols, SDK, and toolchain.
https://dxos.org
MIT License
304 stars 25 forks source link

[docs] consider switching off of VuePress #6569

Open seagreen opened 1 month ago

seagreen commented 1 month ago

VuePress is deprecated, but that's not a big deal. Honestly it could be an asset if looked at from a certain way.

However, we're hitting a number of issues with it:

Animations are too long

6548

The sidebar mixes up page hierarchy with headers/intra-page ToC

I keep getting confused between this (a huge chunk of hierarchy with lots of pages): image

with this (which is just a single page with some sections): image

if I'm getting confused then casual passersby are definitely getting confused.

(VitePress for instance shows headers/intra-page ToC on the right instead of the sidebar.)

The sidebar jerks around during normal operation

Almost each click in the sidebar causes the sidebar contents to jerk upwards, since VuePress only allows one sidebar hierarchy open at once, and you'll almost always be traveling from top-to-bottom and have something open already.

We'd like another theme anyway

Discussed with @thure: https://github.com/dxos/dxos/issues/6551

seagreen commented 1 month ago

I think turning off nested header links and then making the sidebar not collapsible might mitigate multiple of these problems at once, I'll try it out at some point.

wittjosiah commented 1 month ago

@seagreen I don't think we have any particular attachment to VuePress. At the time we adopted it, it was just the only thing we found that satisfied our requirements (e.g. vitepress did not support the types of customization that we felt were needed). Previously we were using docusaurus but the webpack build times were killing us.

Astro looks like a solid option today and might be worth trying out at some point for docs, but as you say it's probably not a high priority.

seagreen commented 1 month ago

Previously we were using docusaurus but the webpack build times were killing us.

Wow, well you did your due diligence. Docusaurus was one of the options I was going to mention, alongside VitePress and Astro Starlight.

as you say it's probably not a high priority.

Agreed, it works well enough.

seagreen commented 3 weeks ago

I'm not sure who to credit because I didn't change anything, but intra-page sections now show on the right instead of being mixed into the left sidebar, enormous improvement:

image

seagreen commented 3 weeks ago

Oh, it's just screen width. With a wide enough screen you see what's in the screenshot above and it works nicely.