Create-react-app: 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:

• [x] Initial setup of Docusaurus (@amyrlam / #5227)
• [x] Removing the blog feature from Docusaurus (@selbekk / #5239)
• [x] Removing sample content and pages (@selbekk / #5242)
• [x] Updating the siteConfig.js file with correct names (@selbekk / #5243)
• [x] Add favicons and og-images from the reactjs.org page (@selbekk / #5244)
• [x] Set up basic documentation structure (@selbekk / #5245)
• [x] Change the color scheme to something more React-y (@selbekk / #5249)
• [x] Update footer links (@selbekk / #5251)
• [x] Create an initial front page design (@selbekk / #5341)
• [x] Create getting started docs (@selbekk / #5344)
• [x] Create user guide docs (@selbekk / #5347)
• [x] Split up user guide docs into sections (@selbekk / #5347)
• [x] Set up Algolia search https://github.com/facebook/create-react-app/pull/5551
• [x] Change the mobile navigation colors (@selbekk / #5398)
• [x] Improve visibility of text links in docs (@selbekk / #5357)
• [x] Add some more content to the landing page (@selbekk / #5398)
• [x] Launch site on Github Pages (?)
• [x] Update GitHub readmes etc to reference the website
• [x] 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. :slightly_smiling_face: 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.

• [x] 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.

• [x] 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.

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

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

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

• [x] 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!

• [x] Add edit button to docs https://github.com/facebook/create-react-app/pull/5492
• [x] Can close https://github.com/facebook/create-react-app/issues/5209 (woot)
• [x] Get rid of README so not duplicated
• [x] Bring in ~last few weeks of edits to README to /docusaurus
• [x] Should still add Algolia (from the thread above ^ https://community.algolia.com/docsearch/who-can-apply.html) with Docusaurus instructions @amyrlam https://github.com/facebook/create-react-app/pull/5551
• [ ] Set up docs to release from CI https://github.com/facebook/create-react-app/pull/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 😄: https://github.com/facebook/Docusaurus/pull/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: https://github.com/facebook/create-react-app/pull/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 :wave:

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: https://github.com/facebook/create-react-app/pull/5551

[iansu]

Versioning is probably something we'll want eventually. I created an issue so we don't forget about this: https://github.com/facebook/create-react-app/issues/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 https://github.com/facebook/create-react-app/issues/5536

[endiliey]

Seems that CI is not yet setup for CRA documentation.

[stale[bot]]

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!