Migrate React Native website to Docusaurus V2 #2263

Simek · 2020-10-20T18:15:06Z

This PR migrates the React Native website to Docusaurus V2.

This is an effect of collaboration with @slorber and MLH Docusaurus team (@darshkpatel & @teikjun).

It is the initial import, rebased against current master in the main repository.

Refs: #2146, #2139

Fixes #2208, Fixes #2054

Preview

https://deploy-preview-2263--react-native.netlify.app

Noticeable changes for website user

SPA - reduced page load times, more fluid navigation
additional dark theme and theme toggle (dark theme Snacks too)
build in tabs sync
Snacks appears on mobile without the preview but with link to open example in Expo app
blog posts are now searchable
code blocks content can be copied by click - "Copy" button appears on hover
old versions and next page have a notice for users that they are reading old or upcoming version of the page

Noticeable changes for contributors/maintainers

announcement bar support out of the box
MDX fragments - which allows to split content and helps to maintain large pages (example: Environment Setup)
extended page customizability and theme components swizzling
improved build times
still growing set of ready to use plugins - https://v2.docusaurus.io/docs/using-plugins/
 tag for blog posts to hide the details on the post list, blog posts tags

You can read more about V2 features and changes in the official documentation:

https://v2.docusaurus.io/docs/

This reverts commit 0a314ba.

…mp (#12) * fix local build, basic theme overrides, header reorder, docusaurus bump * add navbar override group, update navbar typography * tweak version switcher and hr design * update page links style, fix text color issues * use docsVersionDropdown in navbar * fix validation warning * footer design tweaks, jsx as default prism language * add native code banner, fix version label design, update notes style * static dark navbar, color fix, docusaurus bump * tweak dark theme, fix page shrinking issue * navbar UI and positioning tweaks, update blog page * sidebar spacing, minor color tweaks

* add additional languages for prism * set up custom theme for prism * customize according to solarized dark theme * add custom syntax highlighting from react-native * rename theme file, add Kotlin, fix one ObjC block Co-authored-by: Bartosz Kaszubowski <gosimek@gmail.com>

* add line highlighting with the correct syntax * use css to display line highlighting * move css for line highlighting into page overrides section

…on and tags

Simek · 2020-10-27T16:29:01Z

The archive branch website deploy has been set up and RN Archive is available under https://archive.reactnative.dev/ URL.

In theory, having V1 archive up and running makes this PR ready to review and merge 🙂

cpojer · 2020-10-28T01:43:28Z

What are the next steps for this PR? Can you make a checklist in the summary of this PR? Let me know when you need me for final review.

Simek · 2020-10-28T09:19:49Z

What are the next steps for this PR? Can you make a checklist in the summary of this PR? Let me know when you need me for final review.

@cpojer I have posted all the steps within the migration plan last week. Since V1 Archive is deployed this PR should be ready to merge. The commits that appears in this PR lately are just a small tweaks which should not affect the functionality and break the deployment in any way.

Currently we are only not sure if V2 deploy will work from master (after the merge) but there was no way to check this earlier, we are ready to hot fix issues on merge.

When the V2 deploy will be finished we need to ask Algolia to update the search index and recrawl the website. There are also several minor checks that need to be done after the deployment, for example: if the Google Analytics events are tracked correctly, but all major checks or task are done.

cpojer · 2020-10-28T09:21:27Z

Thanks for clarifying. I will review it tomorrow and merge it then.

cpojer

Amazing, what a huge amount of work. Thank you so much for making this happen.

sunnylqm · 2020-11-05T09:49:06Z

@Simek I found some docs are reverted to an older version like this one e622c6a#diff-941914e9c6da4d386c78dcde541e7cc9be34624e543dfccbad380409d8e81813L152-L162

Simek · 2020-11-05T09:59:58Z

Hi @sunnylqm, it is not clear what changes are exactly missing, remember that the tabs code has changed so the diff might be misleading.

Please check the page file in the master docs and let me know if problem occurs in there - https://github.com/facebook/react-native-website/blob/master/docs/building-for-tv.md.

In a meanwhile I will compare master with archive branch and try to find the issue.

sunnylqm · 2020-11-05T10:04:12Z

@Simek That doc in master is incorrect (older) after the migration commit as I showed above

Simek · 2020-11-05T10:10:09Z

@sunnylqm Can you show me somehow where exactly is the issue which you are referring? Can you quote the missing paragraph or sentence on the new site?

At the first glance content on https://reactnative.dev/docs/building-for-tv and https://archive.reactnative.dev/docs/building-for-tv pages looks the same.

sunnylqm · 2020-11-05T10:11:35Z

I think maybe it's because the master version did not build into versioned doc. For the content, it's obvious TabBarIOS and ListView are deprecated long time ago.

So if you take the doc from versioned folder, there might be more inconsistence (not all doc changes go into version folder right away)

Simek · 2020-11-05T10:18:09Z

I think maybe it's because the master version did not build into versioned doc. For the content, it's obvious TabBarIOS and ListView are deprecated long time ago.

So if you take the doc from versioned folder, there might be more inconsistence (not all doc changes go into version folder immediately)

@sunnylqm Sorry, but I don't understand you.

My last idea is that you are looking for additional known issues on Android TV which were only applied to the next docs before the migration, so they are only visible in the next docs: https://reactnative.dev/docs/next/building-for-tv

sunnylqm · 2020-11-05T10:19:11Z

@Simek See this commit 6677d7a#diff-941914e9c6da4d386c78dcde541e7cc9be34624e543dfccbad380409d8e81813
It's reverted, isn't it?

sunnylqm · 2020-11-05T10:22:38Z

If you take the doc from versioned folder and copied them back to master, some changes that haven't build will get lost. Do I make myself clear?

Simek · 2020-11-05T10:30:21Z

@sunnylqm You should mention #2126 at the beginning. 😉 Now I can clearly see and can confirm that this change has been somehow lost during the migration. Would you like to prepare PR to fix this?

If you take the doc from versioned folder and copied them back to master, some changes that haven't build will get lost

The versioned docs were not copied into next docs during the migration. You can check the whole process in the fork created specially for this migration: https://github.com/react-native-website-migration/react-native-website

sunnylqm · 2020-11-05T10:33:40Z

And i noticed the edit link now changed to versioned doc(it was linked to master before), which may not be a good choice.
For a common pattern we should commit to master first then cherrypick to current release right?(either automatically or manually)

Simek · 2020-11-05T10:47:08Z

This is how Docusuaurs V2 "Edit Page" links works and there is no option to change that at this moment. We can always create PR for that, but I'm personally looking at this as an improvement.

When all links were leading to the next version potential contributors were often confused, because they want to fix something on the page they are reading, but after "Edit Page" link click they were seeing different page content or the issue they were looking for was missing on the GitHub file which was opened.

For a common pattern we should commit to master first then cherrypick to current release right?(either automatically or manually)

They way we handle PRs heavily depends on the kind and scope of the issue or improvement, the most common pattern is to edit only next docs, with no backporting. More important changes are usually backported to the latest version too (0.63 at this moment). Also there is no automatic mechanism to backport the changes to older docs, and in 99% of cases version docs generated once will not be regenerated.

sunnylqm · 2020-11-05T11:02:55Z

The question is that what's the cause for that lost?(I don't know what to check on that migration repo) If it's not copied from versioned docs, the only possibility I can come up with is it's copied from a snapshot on master?
Either way I am worrying about more commits may lost.

slorber · 2020-11-05T11:13:32Z

@sunnylqm I agree with you and it's also a problem for docusaurus website.
I want to add an option so that we can configure the edit link of each version independently.
You can make the RN 0.63 (latest) target the master docs in priority for example. I'd also prefer to edit the master docs in such case because if we merge by mistake a PR that only target RN. 0.63 we end up loosing the info for RN 0.64

This is also needed because some of our users are assembling md files from external repos, git submodules etc... Also we'll explore how to handle git-based CMS tools like Forestry/Tina/NetlifyCMS, in which case the edit link may rather target the edition UI instead of the git file.

So, it's not ready today but it's something we'll definitively support soon

darshkpatel and others added 30 commits October 20, 2020 19:53

remove unused versions

14a6368

include changes to en.json

3f9fc62

update dependencies

897a149

upgrade to v2 config

2c3e083

create a customTheme.css file and update yarn.lock

9642fe9

move customTheme.css

dcf3243

Upgrade blog file for v2

ef3733c

upgrade sidebar configs

9eb122b

upgrade sidebar config for v2

bcdc565

Rename and fix errors in 0.60 and 0.61 docs

1d313ac

Rename and fix errors in 0.62 and 0.63 docs

0dfebf4

add .docusaurus to gitignore

3154f1e

change path for docs plugin

b2cdf1b

update circleci config for v2 build path

e310fd3

update scripts for v2 paths

9ad72a9

update netlify config

0abd9de

fix errors in docs

4aac15b

update netlify.toml

81c67a7

resolve http warning

9580a66

revert "fix errors in docs"

16f0a93

fix errors in docs

c3f22d4

resolve merge conflict

57cbf52

fix errors in upstream's appregistry

ba60e69

Revert "Rename and fix errors in 0.60 and 0.61 docs"

7e8a2f0

This reverts commit 0a314ba.

fix errors in 0.60 and 0.61 docs

cd9763b

add line highlighting (#18)

f82da76

* add line highlighting with the correct syntax * use css to display line highlighting * move css for line highlighting into page overrides section

remove V1 announcement bar code

d881952

sidebar subcategories should not be collapsed by default

8f6a92e

Simek and others added 4 commits October 26, 2020 12:12

fix few minor issues on the homepage, add missing links

8a9fa8b

small TOC tweak and spacing fix on the homepage

f5de585

convert blog categories, fix blog post warnings, style read more butt…

2c84b42

…on and tags

fix docs editUrl typo

a92b209

Simek requested review from rachelnabors and cpojer October 27, 2020 16:29

Simek added 2 commits October 27, 2020 18:52

add information about archive, fix code blocks scrollbars

31efc5d

adjust code tags style, improve native code banner in dark mode

32a40b0

cpojer approved these changes Oct 29, 2020

View reviewed changes

cpojer merged commit e622c6a into facebook:master Oct 29, 2020

slorber mentioned this pull request Oct 29, 2020

fix Docusaurus v2 CircleCI/GH-pages deployment #2273

Merged

Simek mentioned this pull request Oct 29, 2020

Is Website is down? #2276

Closed

Simek mentioned this pull request Nov 5, 2020

docs(v2): add React Native website to the showcase facebook/docusaurus#3695

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate React Native website to Docusaurus V2 #2263

Migrate React Native website to Docusaurus V2 #2263

Simek commented Oct 20, 2020 •

edited

Loading

Simek commented Oct 27, 2020

cpojer commented Oct 28, 2020

Simek commented Oct 28, 2020 •

edited

Loading

cpojer commented Oct 28, 2020

cpojer left a comment

sunnylqm commented Nov 5, 2020

Simek commented Nov 5, 2020

sunnylqm commented Nov 5, 2020

Simek commented Nov 5, 2020 •

edited

Loading

sunnylqm commented Nov 5, 2020 •

edited

Loading

Simek commented Nov 5, 2020 •

edited

Loading

sunnylqm commented Nov 5, 2020

sunnylqm commented Nov 5, 2020

Simek commented Nov 5, 2020

sunnylqm commented Nov 5, 2020

Simek commented Nov 5, 2020 •

edited

Loading

sunnylqm commented Nov 5, 2020

slorber commented Nov 5, 2020

Migrate React Native website to Docusaurus V2 #2263

Migrate React Native website to Docusaurus V2 #2263

Conversation

Simek commented Oct 20, 2020 • edited Loading

Preview

Noticeable changes for website user

Noticeable changes for contributors/maintainers

You can read more about V2 features and changes in the official documentation:

Simek commented Oct 27, 2020

cpojer commented Oct 28, 2020

Simek commented Oct 28, 2020 • edited Loading

cpojer commented Oct 28, 2020

cpojer left a comment

Choose a reason for hiding this comment

sunnylqm commented Nov 5, 2020

Simek commented Nov 5, 2020

sunnylqm commented Nov 5, 2020

Simek commented Nov 5, 2020 • edited Loading

sunnylqm commented Nov 5, 2020 • edited Loading

Simek commented Nov 5, 2020 • edited Loading

sunnylqm commented Nov 5, 2020

sunnylqm commented Nov 5, 2020

Simek commented Nov 5, 2020

sunnylqm commented Nov 5, 2020

Simek commented Nov 5, 2020 • edited Loading

sunnylqm commented Nov 5, 2020

slorber commented Nov 5, 2020

Simek commented Oct 20, 2020 •

edited

Loading

Simek commented Oct 28, 2020 •

edited

Loading

Simek commented Nov 5, 2020 •

edited

Loading

sunnylqm commented Nov 5, 2020 •

edited

Loading

Simek commented Nov 5, 2020 •

edited

Loading

Simek commented Nov 5, 2020 •

edited

Loading