[Long Term Plan] Move to docusaurus

[swyxio]

thanks to many people's contributions the cheatsheet is starting to get long, and im starting to think about how to scale this thing. i think FB's docusaurus is a good way to maintain readable and searchable react+typescript docs, while still allowing us to edit markdown easily.

the other big wishlist item i have is to note down the specific version features of Typescript that have particular significance or application in React. There will be a lot coming down with 3.0 but its hard for me to keep track with what happened since 2.0. a series of sections on each TS version would be an interesting an idea and allows people to learn cumulatively or starting from whatever base of knowledge they have.

[hedgerh]

Yooo I just came across this. Let's do itttt. I could start spinning it up?

[swyxio]

this hasn't been as high of a priority since i split the single cheatsheet out to multiple. so far i've had no complaints. do you think its a priority? i personally no longer do

[hedgerh]

I think the big benefit would be improved navigation. I usually ctrl+f to find things, but when I’m looking for “refs”, for instance, I’ll have to skip through a few different results to find what I need. Having a table of contents would help with discovering things you didn’t even know you wanted to know, as well.

I actually missed that there was an Advanced section until the other day. I also think I’ve had a time or two where the syntax or tip I was looking for was hidden in one of the accordions.

I think you could even just keep it as two big documents in docusaurus, but have the sidebar. I’m not sure about splitting it into a bunch of documents, necessarily. Maybe it’d be a good idea, but I’d want to request feedback from people who use it to make sure we weren’t making a worse experience by changing things.

[swyxio]

yeah so a docusaurus + algolia setup maybe in order. well if you’d like to try an mvp i’d be happy to deploy and point people to it!

[hedgerh]

Wanted to get your thoughts on organizing the docs.

There's a lot of great information in here that gets lost in the mix because it's intermingled with the material on typing the React API/common patterns. How do you feel about isolating the React API material into a "How To Type" section?

Unfinished draft so far:

Setup:
  Prerequisites
  React + TypeScript Starter Kits
  Import React

How To Type:
  Props
    Basic Prop Types Examples
    Useful React Prop Type Examples
    Tip: Comments on Props
  Function Components
  Class Components
  Hooks
    useState
    ...
  Default Props
  Events & Forms
  Refs (createRef/forwardRef)
  Context
  Portals
  Error Boundaries
  Concurrent React/React Suspense
  Reusable Components
    Higher Order Components
    Render Props
    `as` props

FAQ:
  Types or interfaces?

Helpful Tools & Utilities:
  Utility Types
  Type Zoo

Recipes/Patterns:
  Props: One or the other but not both
  Props: Must Pass Both
  Props: Can Optionally Pass One Only If the Other Is Passed
  Omit Attribute from a type
  Type Zoo
  Extracting prop types of a component
  Handling Exceptions
  Creating React + TypeScript Libraries
  Third Party Libraries
    Dealing with broken @types packages

It'd be cool to be able to surface all of the non-API stuff people should know in an easily discoverable way. For example, I didn't realize there was a way to import React normally with TS, since I use this as a reference, and never read the Setup section!

[swyxio]

hmm! sure. this can be useful as a broader re-examination of the structure we have right now. it wasnt quite a conscious design, it just kinda grew.

[hedgerh]

not really liking working with docusaurus, and having trouble getting it to do what I want. Trying to get one that’ll show the main sections and subsection headings in the left sidebar, but coming up empty.

Docz is super easy to work with, but those sub-sections aren’t shown in the sidebar unless you’re on the page for that section

[swyxio]

docusaurus maintainers are pretty responsive, just reach out im sure your usecase isnt new!

even tho i help maintain docz, its kinda dead right now. would recommend docusaurus.

[swyxio]

done thanks to @slorber :) #233