Porting documentation to Docusaurus

[selbekk]

Ref #5209, this issue will work as a base for planning the work of creating a Docusaurus documentation website for create-react-app.

Task list

An initial task overview might look like this:

• Initial setup of Docusaurus (@amyrlam / Initial setup of Docusaurus #5227)
• Removing the blog feature from Docusaurus (@selbekk / 5238 removing blog from Docusaurus #5239)
• Removing sample content and pages (@selbekk / 5238 Removing sample pages #5242)
• Updating the siteConfig.js file with correct names (@selbekk / Set the project name and owner correctly #5243)
• Add favicons and og-images from the reactjs.org page (@selbekk / Update favicon and OpenGraph images #5244)
• Set up basic documentation structure (@selbekk / 5238 set up basic docs structure #5245)
• Change the color scheme to something more React-y (@selbekk / Set the color palette to something a bit more React-y #5249)
• Update footer links (@selbekk / Add SoMe links to documentation #5251)
• Create an initial front page design (@selbekk / Add callouts and logo #5341)
• Create getting started docs (@selbekk / Add some headings to the getting started section #5344)
• Create user guide docs (@selbekk / Port user guide over #5347)
• Split up user guide docs into sections (@selbekk / Port user guide over #5347)
• Set up Algolia search Add Algolia search bar to Docusaurus #5551
• Change the mobile navigation colors (@selbekk / Add some front page content #5398)
• Improve visibility of text links in docs (@selbekk / Potpourri #5357)
• Add some more content to the landing page (@selbekk / Add some front page content #5398)
• Launch site on Github Pages (?)
• Update GitHub readmes etc to reference the website
• Decide what to do with the template README
• Update bit.ly/CRA-PWA link

This task list will be updated, edited and changed as we come up with more tasks, or split larger ones up into smaller ones.

Documentation structure

There are many ways of structuring the content found in this repo, but I think a good first approach is to split it into two parts:

• Getting started (some of the information from the README.md file can go here)
• User Guide (as is, for now)

From there, we can split it up into more narrow "groups", if we find it appropriate and helpful for the user.

[gaearon]

This makes sense. I think we should figure out a good high-level structure for User Guide before diving into this work. We'd want to group it into higher level sections.

[selbekk]

That's fine by me. 🙂 You can do some thinking on that while I start with some of the more "get-it-done"-tasks? :)

[selbekk]

Challenge: Docusaurus requires a /docs folder on the root scope of the project - but I understand if you want to hold off on creating one to not mislead your users while we set this up.

[Timer]

Adding a top level /docs section is fine. Just add a README.md pointing to normal user guide for now.

[gaearon]

A few concerns before we launch this for the first time.

• We'll need to make the front page copywriting more compelling. Some tools specifically use "no need to eject" as a selling point these days. We should adapt and try to explain the benefits of CRA approach — specifically, easy updates. That's something I can work on just after everything else is ready and before we publish.

• There's probably some project-specific branding we should do. Like choosing a color palette and having a separate logo. For now it's fine though, we can add it later.

• How-to section is too long and is a mix of everything. We should try to further split it into separate sections grouped by some common topic. E.g. "Styles and Assets", "Backend Integration". I also don't like "How-to" as a title.

• Long page titles like "Generating Dynamic <meta> Tags on the Server" look bad in sidebar. We should shorten them, e.g. "Title and Meta Tags" which can unify both topics.

• Testing and Deployment sections should probably come before more esoteric tasks.

• "Updating to new releases" should be somewhere much earlier.

• Avoid tiny pages. If a page is tiny it can be probably unified with some other page.

• There's "API reference" in sidebar, remove?

[selbekk]

So most of this is done, with the exception of copywriting and branding things.

[selbekk]

We should probably make the docs searchable as well, but I think we can release this as is now.

@amyrlam has done some research here. We need to configure Docusaurus and then we need to set up Algolia's DocSearch.

The latter, which will create an API key, is probably best done by one of the maintainers. Once it's done, send me the API key, and I'll create a pull request enabling the search feature.

[amyrlam]

Really awesome this is out! Docusaurus folks are super excited!

• Add edit button to docs Add "edit" feature to Docusaurus pages #5492
• Can close Creating a documentation web site #5209 (woot)
• Get rid of README so not duplicated
• Bring in ~last few weeks of edits to README to /docusaurus
• Should still add Algolia (from the thread above ^ https://community.algolia.com/docsearch/who-can-apply.html) with Docusaurus instructions @amyrlam Add Algolia search bar to Docusaurus #5551
• Set up docs to release from CI [WIP] Set up docs to release from Appveyor CI #5496 (WIP)

[gaearon]

Bring in ~last few weeks of edits to README to /docusaurus

I did that. I also truncated the generated README to be very short although we can still make it shorter.

[amyrlam]

Ah sorry about that - makes sense now. The README seems good as-is! Updated my comment and other checkboxes above.

Do you still want to add Algolia search? Could be a quick win. CRA team will need to sign up https://community.algolia.com/docsearch/who-can-apply.html to get the API key.

Docusaurus has already added CRA as a user 😄: facebook/docusaurus#1050

[gaearon]

CRA team will need to sign up https://community.algolia.com/docsearch/who-can-apply.html to get the API key.

You're a part of the team now, so maybe you could do it? :-)

[amyrlam]

Ok cool - sure thing, I'll do that

[gaearon]

We also need to set up docs to release from CI.

[amyrlam]

Submitted to Algolia - sounds like may take a few days. Should be a straightforward PR!

//

As for setting up docs to release from CI...not super familiar with GitHub Pages or Appveyor but took a stab at it here: #5496 (work in progress)

Let me know if you have any ideas to help move forward. Also if you could fill in some of the git stuff. TIL the skip_commits was why Appveyor wasn't running on the docusaurus branch.

[petetnt]

This is awesome, nice work!!

Something that would be eventually nice would be versioning the docs like the React ones are and pointing the versioned docs in the template generated by CRA 👍

[endiliey]

Hello 👋

Docusaurus maintainer here. Really happy to see this happening. Thanks for doing this to all people involved. ☺

[amyrlam]

@petetnt 👋 Was thinking of waiting to version docs til https://github.com/facebook/docusaurus v2.0 is out. But if there are a lot of changes, could start versioning docs? Would be good to get the docs on continuous deployment first...

//

Here's the Algolia PR, woot: #5551

[iansu]

Versioning is probably something we'll want eventually. I created an issue so we don't forget about this: #5560

[peterbe]

Since this issue is still open, I thought I'd pile on...:

http://bit.ly/CRA-PWA is mentioned in many places. It's now wrong.

It redirects to https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#making-a-progressive-web-app. But it should redirect to https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app instead.

Who has the keys to that bit.ly account?

[peterbe]

@selbekk Can you add my point (comment right above) about the bit.ly link redirect to your todo list in the issue description?

[petetnt]

@peterbe check out #5536

[endiliey]

Seems that CI is not yet setup for CRA documentation.

[stale]

This issue has been automatically marked as stale because it has not had any recent activity. It will be closed in 5 days if no further activity occurs.

[selbekk]

I guess this issue could be closed now. Thanks for all participating members!