rewrite docs suggestion

[jacobdalamb]

I think a docs rewrite using starlight would be great enhancement for the site. It could benefit from better performance and accessibility, improved SEO, can maintain the existing design with a more streamlined look and has a excellent developer experience.

[fdncred]

we're always interested in making things better but it's not clear how that is true with starlight.

[jacobdalamb]

starlight

I can I think of a few improvements on top of the ones I mentioned. Starlight comes with copy and paste buttons for code blocks, "gives you built-in frontmatter validation with TypeScript type-safety", built-in components, and in my opinion custom block containers (tip, caution, and note) that are visually styled better.

[fdncred]

And does it support styling/highlighting nushell language syntax?

[jacobdalamb]

And does it support styling/highlighting nushell language syntax?

Yes. https://github.com/shikijs/textmate-grammars-themes/blob/main/packages/tm-grammars/README.md

[fdncred]

It would be nice to have something that supports tree-sitter-nu too at some point. That grammar is coming along nicely.

[hustcer]

There are tons of SSG tools, and I don't think they have great advantage over Rspress, especially talking about building performance. BTW: Rspress adds shiki plugin support recently.
Glad if you prove me wrong.
Related: #1126

[jacobdalamb]

There are tons of SSG tools, and I don't think they have great advantage over Rspress, especially talking about building performance. BTW: Rspress adds shiki plugin support recently. Glad if you prove me wrong. Related: #1126

Another great alternative to the current docs. Both are good.

[jacobdalamb]

It would be nice to have something that supports tree-sitter-nu too at some point. That grammar is coming along nicely.

Would you be interested in a PR to see what the site would look like using Starlight?

[fdncred]

I personally wouldn't mind seeing a PR but it would have to:

1. be as easy or easier to manage than what we have now
2. look as good or better than what we have now
3. translations would need to work as good or better than what we have now
4. @hustcer would need to approve of it since he manages a lot of the site for us now (we'd have to have other core-team members approve too in order to move to it, but not really needed for a preview)
5. we'd also need a way to preview it somehow

[hustcer]

@jacobdalamb

There are two things I most care about:

1. Build speed, we have lots of docs now, the build speed is not fast enough, in the future we also intend to support multiple versions and the build speed requirements are higher. We do not support multiple versions also due to the slow build speed.
2. The new approach need to support multiple versions, which is especially important after version v1.0. We may have docs for v1 and v1.1, etc. at the same time.
   You can try to solve these two points with Starlight.

[NotTheDr01ds]

I'd like to consider closing this as a duplicate of #1126 and continuing the discussion there. If agreed, go ahead and close it. I'll then copy over a summary of new information in this issue so it can be consolidated in one place.

[fdncred]

ya, seems like a dupe to me. thx.