Feat/website rewrite

[jacobdalamb]

A rewrite of Nushell docs using Starlight

Related issue: #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 withastro/starlight#957

• Average build speed: 53 seconds
• Should be easier to manage using autogenerated groups
• Personally think it has a better design
• Translations are as good as they are currently (maybe better?)

[sholderbach]

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

[sholderbach]

Should they all be ignored during formatting?

[sholderbach]

Did you run into any new problems with the typos ci step?

[jacobdalamb]

Oh no, I wasn't sure what the file was for. I'll add it back.

[sholderbach]

nu twice for the codeblock annotation doesn't make sense. Did you maybe run a global search and replace here?

While it makes sense for most of the Nushell code to standardize on one there may be a few snippets around that use different languages.

[jacobdalamb]

My bad, I did run a global search and replaced there.

[sholderbach]

Am I reading this right that the h1 headings are completely replaced by the title in the metadata and the highest level you can declare yourself is markdown h2?

[jacobdalamb]

Unfortunately, the h1 headings are completely replaced by the title in the metadata.

[sholderbach]

Would we always need to figure out the sidebar order in the subpages?

[jacobdalamb]

It's easier than having to manually configure the navbar navigation. It's a relatively low cost trade.

[sholderbach]

As the pages are already autogenerated from the internal help via a script, templating this again feels a little bit overkill :)

[fdncred]

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

Markdown

Nushell Tables

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]

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]

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

Markdown

Nushell Tables

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.