WIP: Implement Docssaurus

[raulfdm]

Hold on ✋. This PR is under construction. I'll write a much more detailed description later on

Live docs https://raulfdm.github.io/react-typescript-cheatsheet/

TODO

• Write how to add new docs
• Write how to run the website locally
• Squash into better commits
• Add Logo
• Review unnecessary side_title + title
• Clean up commented code
• Replace markdown file references (page linking) with new pages (ie. see our [Commenting Components](/ADVANCED.md#commenting-components))
• Enable translations
  • It needs the whole website in English be accepted and online;
  • Needs Crowdin account (https://docusaurus.io/docs/en/translation#crowdin) + api keys
  • bring existing translations
• Enable Search (LAST STEP)
  • needs the website finalized, online and preferable with translations;
  • maintainers needs to submit algolia docs form (https://docsearch.algolia.com/)

Changes

• Remove action prettier validation in favor of pre-hook prettier format. In that way every file committed will be already well formatted;
  • [RETHINK] WIP: Implement Docssaurus #214 (comment)
• Set caching for prettier action;
• Add action to deploy via Gh pages
• Add Github pages action
• Add Docssaurus documentation;
• Split docs into small chunks

Before merge

• Change user name everywhere;
• Ask to add GITHUB_TOKEN key

Points to discuss

• advanced -> props. Could be combined into 1 "props guide"
• advanced -> hocs. Does it makes sense to mention here? Should the entire HOCs file be inside advanced guides?
• Should menus collapse?
• Where it'll be hosted?

[swyxio]

that github preview seems broken - wanna use Netlify or something else?

[raulfdm]

Indeed. I was trying to set it up via gh-pages to make easier the deployment but it seems more complicated than just setup a simple netlify

[raulfdm]

@sw-yx I think now it's working.

Could you take a look and share your thoughts about it? Just to see if I should continue in this way.

[eps1lon]

Remove action prettier validation in favor of pre-hook prettier format. In that way every file committed will be already well formatted;

I have pre-commit hooks disabled globally and others might too. Why do we need to disable the action?

[raulfdm]

Remove action prettier validation in favor of pre-hook prettier format. In that way every file committed will be already well formatted;

I have pre-commit hooks disabled globally and others might too. Why do we need to disable the action?

lol... I didn't know it's even possible to disable git hooks globally.

I mean, it's a clear step, right? Why should a commit not formatted be committed? I just propose to skip this kind of simple validation.

But knowing that, I'll keep both

[swyxio]

lookin good! its coming along!

[raulfdm]

@sw-yx I think I have the bare minimum.

Only missing HOC + Migration but now I need some guidance how you see yourself writing these guides.

I'll drop some questions bellow. If you and/or more maintainers can discuss about each topic would be amazing. I don't want to take core decisions without the opinion from the ones which maintain that.

1. Can I fully disable "blog" feature or do you intend to use it?
2. Is the color scheme already good?
3. Does the file HOC lives inside advanced? Take a look on the current folder structure (<root>/docs/*)
4. Should the menus be collapsible? (ie collapse Basic in other to see only advanced
5. Should MIGRATING be another root level docs? (ie. "basics", "advanced", "migrating")
6. Given the current way I structure the files, are the any concerns in how did I split the chunks?
7. Should "my question isn't here" be a "initial" section?

Also just take a look on it and share what could be different, or better.

[eps1lon]

Why should a commit not formatted be committed?

I don't want to argue personal workflow. A bad commit shouldn't be merged into master which is why we have CI via github actions. The state of the PR during development is not relevant.

[raulfdm]

@eps1lon Rolled it back!

[swyxio]

1. Can I fully disable "blog" feature or do you intend to use it? no, can disable
2. Is the color scheme already good? sure :)
3. Does the file HOC lives inside advanced? Take a look on the current folder structure (<root>/docs/*) no, HOC is a separate, root level category, since HOC is mostly legacy compared to Hooks and has a lot of TS challenges, I split it out
4. Should the menus be collapsible? (ie collapse Basic in other to see only advanced) not required
5. Should MIGRATING be another root level docs? (ie. "basics", "advanced", "migrating") yes, root level
6. Given the current way I structure the files, are the any concerns in how did I split the chunks? i think its fine! just need to have good search IMO
7. Should "my question isn't here" be a "initial" section? good question. I don't really know. Let's say yes!

[raulfdm]

Nice!

Well, so a catch up about what I did:

• Create HOC and Migration into root docs level;
• Add some Footer links. Let me know if you want to having something in the Community section, otherwise we can remove it.
• Also remove the extra buttons in initial section
• Add the official repository as Github URLS

Search

About searching, maybe this should be the last step. It'll be necessary you or someone submit the following form asking this service to Algolia.

• https://docsearch.algolia.com/

Then, we'll get the API keys and enable search into siteConfig.js

Translations

Docussaurus uses Crowdin to provide translations. It's a paid service but for open source projects, it's free due a form submission.

• https://docusaurus.io/docs/en/translation#crowdin
• https://crowdin.com/page/open-source-project-setup-request

[swyxio]

ok awesome i'll try to set that Algolia thing up.

i've loaded myself up with a big project that is keeping me super busy, sorry for the delayed response - I'm gonna merge this in now, thanks for the initial lift and we'll announce this when we have the site up with Algolia!