search

nushell / nushell.github.io

Nushell's main website, blog, book, and more
https://www.nushell.sh/book/
MIT License
166 stars 408 forks source link

Feat/website rewrite #1276

Open jacobdalamb opened 6 months ago

jacobdalamb commented 6 months ago

A rewrite of Nushell docs using Starlight

Related issue: https://github.com/nushell/nushell.github.io/issues/1231

There may be a way to build a versioning system on top of Starlight using routing and is a feature the team currently has a discussion open on it https://github.com/withastro/starlight/discussions/957

fdncred commented 6 months ago

I also noticed that some things don't look quite right.

Markdown image

Nushell Tables image

Command Reference is really slow. Maybe should be broken up by letter than having one massive page.

Search

Cookbook 404

Not a bad first start.

jacobdalamb commented 6 months ago

Thanks for working through all of this! I gave it a try locally to get a feel for it.

Before we decide on whether we make a switch and you having to tweak more things I have a few questions mostly on how we manage the pages:

  • Would there be a clear path towards how we could build our own docs versioning?
  • a few pages have changed so much that git doesn't recognize them as moved and instead just reports a deletion and a new creation. This needs extra care and attention when resolving the merge with the changes from the main branch.
  • (see comments)

When looking at the pages:

  • the missing top menu on the homepage made it less usable to quickly go to either the release notes/blog, or documentation or the different documentation topics (same happens on the 404 page)

    • Does starlight allow you to have different sidebars under the same overall project?
  • the search didn't work for me locally, is this still using the algolia backend or something provided by astro? (@fdncred is looking at the algolia analytics for FAQ questions)
  • Nit: While the look generally feels modern, I personally don't really dig the fake-macOS- windows around the code blocks, as they seem to disrupt the flow in longer text

It seems that some people from the discussion I mentioned earlier about including docs versioning into Starlight said that branches would be the best way as "Folders can get tricky and start to require a lot of manual work" which I agree with.

I'm not sure what you mean by "different sidebars under the same overall project"

Search doesn't work locally, search is provided by Pagefind

No problem, you remove the windows around the code blocks by adding frame="none" or frame="code"

jacobdalamb commented 6 months ago

I also noticed that some things don't look quite right.

Markdown image

Nushell Tables image

Command Reference is really slow. Maybe should be broken up by letter than having one massive page.

Search

Cookbook 404

Not a bad first start.

Oh yeah, for some particular reason prettier changes the format of the coming from bash page and messes it up. I will just go back and fix it then tell prettier not to format that page.