chore: prepare docs for Docusaurus v3 upgrade - 2nd iteration by slorber · Pull Request #3830 · facebook/react-native-website

slorber · 2023-08-25T10:45:36Z

This is a follow-up of #3807

The goal is to adjust docs so that they render exactly the same on MDX v1 and MDX v2.
This permits my visual regression tests to avoid reporting false positives due to MDX behavior changes.

This also permitted to catch a few typos and inconsistencies.

Preview: https://deploy-preview-3830--react-native.netlify.app/

netlify · 2023-08-25T10:48:15Z

✅ Deploy Preview for react-native ready!

Name	Link
🔨 Latest commit	`0e545b2`
🔍 Latest deploy log	https://app.netlify.com/sites/react-native/deploys/64e8a72dd78c200008998623
😎 Deploy Preview	https://deploy-preview-3830--react-native.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

slorber

Ready to review @Simek

slorber · 2023-08-25T10:47:10Z

docs/profile-hermes.md

 3. Right click and choose **Load profile...**

- <img src="/docs/assets/openChromeProfile.png" alt="Loading a performance profile on Chrome DevTools" />
+<img src="/docs/assets/openChromeProfile.png" alt="Loading a performance profile on Chrome DevTools" />


unwanted extra space change list + image layout

Before: https://reactnative.dev/docs/profile-hermes#open-the-downloaded-profile-in-chrome-devtools
After: https://deploy-preview-3830--react-native.netlify.app/docs/profile-hermes#open-the-downloaded-profile-in-chrome-devtools

slorber · 2023-08-25T10:49:17Z

docs/pushnotificationios.md

- `alert` :boolean
- `badge` :boolean
- `sound` :boolean
+- `alert: boolean`
+- `badge: boolean`
+- `sound: boolean`


:xyz, ::xyz and :::xyz are "Markdown Directives" and we turn them on by default in Docusaurus v3 to bring admonition support.

This means you should avoid that in your code (unless escaped) otherwise those annotations will magically disappear when upgrading.

I think it's reasonable to make the boolean part of the inline code block

Before: https://reactnative.dev/docs/pushnotificationios#checkpermissions
After: https://deploy-preview-3830--react-native.netlify.app/docs/pushnotificationios#checkpermissions

slorber · 2023-08-25T10:51:07Z

docs/scrollview.md

  options?: {x?: number, y?: number, animated?: boolean} | number,
  deprecatedX?: number,
-	deprecatedAnimated?: boolean,
+  deprecatedAnimated?: boolean,


looks like a typo

slorber · 2023-08-25T10:52:40Z

docs/touchablenativefeedback.md

 ```

-Creates an object that represents android theme's default background for selectable elements (?android:attr/selectableItemBackground). `rippleRadius` parameter controls the radius of the ripple effect.
+Creates an object that represents android theme's default background for selectable elements (`?android:attr/selectableItemBackground`). `rippleRadius` parameter controls the radius of the ripple effect.


Another "Markdown Directive", we want to avoid them, escape them or wrap them in code blocks.

Otherwise the upgrade will lead to:

slorber · 2023-08-25T10:53:17Z

website/architecture/render-pipeline.md

 In the above example, React creates the new tree using these operations:

-1. CloneNode(**Node 3**, {backgroundColor: 'yellow'}) → **Node 3'**
+1. CloneNode(**Node 3**, `{backgroundColor: 'yellow'}`) → **Node 3'**


looks reasonable to wrap in code block

{ will mess up with MDX 2 and require to be escaped

slorber · 2023-08-25T11:03:37Z

website/blog/2016-08-19-right-to-left-support-for-react-native-apps.md

-   		[[RCTI18nUtil sharedInstance] allowRTL:YES];
+     [[RCTI18nUtil sharedInstance] allowRTL:YES];
   ```

   Android:

   ```java
   // in MainActivity.java
-   		I18nUtil sharedI18nUtilInstance = I18nUtil.getInstance();
-   		sharedI18nUtilInstance.allowRTL(context, true);
+     I18nUtil sharedI18nUtilInstance = I18nUtil.getInstance();
+     sharedI18nUtilInstance.allowRTL(context, true);


Replace tabs with spaces for consistency + avoid extra spacing appearing when upgrading:

slorber · 2023-08-25T11:06:38Z

website/blog/2016-12-05-easier-upgrades.md

 @@ -45,7 +45,7 @@
- 		<dict>
- 			<key>localhost</key>
- 			<dict>
-				<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
-+				<key>NSExceptionAllowsInsecureHTTPLoads</key>
- 				<true/>
- 			</dict>
- 		</dict>
+        <dict>
+            <key>localhost</key>
+            <dict>
+-               <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
+               <key>NSExceptionAllowsInsecureHTTPLoads</key>
+                <true/>
+            </dict>
+        </dict>
 [...]
 ```

 All we need now is to apply this patch to your source files. While the old `react-native upgrade` process would have prompted you for any small difference, Git is able to merge most of the changes automatically using its 3-way merge algorithm and eventually leave us with familiar conflict delimiters:

 ```
-		13B07F951A680F5B00A75B9A /* Release */ = {
-			isa = XCBuildConfiguration;
-			buildSettings = {
-				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+    13B07F951A680F5B00A75B9A /* Release */ = {
+      isa = XCBuildConfiguration;
+      buildSettings = {
+        ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
 <<<<<<< ours
-				CODE_SIGN_IDENTITY = "iPhone Developer";
-				FRAMEWORK_SEARCH_PATHS = (
-					"$(inherited)",
-					"$(PROJECT_DIR)/HockeySDK.embeddedframework",
-					"$(PROJECT_DIR)/HockeySDK-iOS/HockeySDK.embeddedframework",
-				);
+        CODE_SIGN_IDENTITY = "iPhone Developer";
+        FRAMEWORK_SEARCH_PATHS = (
+          "$(inherited)",
+          "$(PROJECT_DIR)/HockeySDK.embeddedframework",
+          "$(PROJECT_DIR)/HockeySDK-iOS/HockeySDK.embeddedframework",
+        );
 =======
-				CURRENT_PROJECT_VERSION = 1;
+        CURRENT_PROJECT_VERSION = 1;
 >>>>>>> theirs
-				HEADER_SEARCH_PATHS = (
-					"$(inherited)",
-					/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include,
-					"$(SRCROOT)/../node_modules/react-native/React/**",
-					"$(SRCROOT)/../node_modules/react-native-code-push/ios/CodePush/**",
-				);
+        HEADER_SEARCH_PATHS = (
+          "$(inherited)",
+          /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include,
+          "$(SRCROOT)/../node_modules/react-native/React/**",
+          "$(SRCROOT)/../node_modules/react-native-code-push/ios/CodePush/**",
+        );
 ```


Replace tabs with space for consistency

Avoid this unwanted extra spacing when upgrading:

Before: https://reactnative.dev/blog/2016/12/05/easier-upgrades#how-does-it-work
After: https://deploy-preview-3830--react-native.netlify.app/blog/2016/12/05/easier-upgrades#how-does-it-work

slorber · 2023-08-25T11:08:00Z

docs/native-components-ios.md

 RCT_CUSTOM_VIEW_PROPERTY(region, MKCoordinateRegion, MKMapView)
 {
-	[view setRegion:json ? [RCTConvert MKCoordinateRegion:json] : defaultView.region animated:YES];
+  [view setRegion:json ? [RCTConvert MKCoordinateRegion:json] : defaultView.region animated:YES];


replace tab with space + reduce indentation for consistency

Avoid this extra spacing when upgrading:

Before: https://reactnative.dev/docs/native-components-ios#events
After: https://deploy-preview-3830--react-native.netlify.app/docs/native-components-ios#events

slorber · 2023-08-25T12:53:21Z

website/blog/2016-08-19-right-to-left-support-for-react-native-apps.md

+<>
 <img src="/blog/assets/rtl-ama-ios-arabic.png" width={280} style={{ margin: 10 }} />
-
 <img src="/blog/assets/rtl-ama-android-hebrew.png" width={280} style={{ margin: 10 }} />
+</>


Adding a fragment here permits to avoid having an extra useless \n char when upgrading to MDX v2.

https://twitter.com/badsyntax/status/1695041116893036746

In practice it's not super impactful, but this change will ensure the 2 images look exactly the same before/after the MDX v2 upgrade.

slorber · 2023-08-25T13:08:58Z

yarn.lock

-  version "1.28.0"
-  resolved "https://registry.yarnpkg.com/prismjs/-/prismjs-1.28.0.tgz#0d8f561fa0f7cf6ebca901747828b149147044b6"
-  integrity sha512-8aaXdYvl1F7iC7Xm1spqSaY/OJBpYW3v+KJ+F17iYxvdc8sfjW194COK5wVhMZX45tGteiBQgdvD/nhxcRwylw==
+  version "1.29.0"


minor update, the only impact I found in my visual tests was this change in Java code blocks:

Before: https://reactnative.dev/docs/headless-js-android#example-usage

After: https://deploy-preview-3830--react-native.netlify.app/docs/headless-js-android#example-usage

elicwhite · 2023-09-01T23:35:17Z

Thanks for the care you put into finding these issues and documenting the diff inline to make it easy to review!

slorber added 7 commits August 25, 2023 11:01

Add quotes

2e5c5bb

Fix useless bold chars

7f63f7d

fix useless extra spacing

8194d1d

fix useless extra spacing

ee6f7c0

avoid remark-directive syntax

7501fae

fix scrollTo codeblock

bda8552

Avoid remark-directive syntax

4667a2e

facebook-github-bot added the CLA Signed label Aug 25, 2023

slorber added 7 commits August 25, 2023 12:57

code blocks, use space instead of tabs

56797fd

code blocks, use space instead of tabs

277a5a8

code blocks, use space instead of tabs

9b45cc8

code blocks, use space instead of tabs

4d7f8e9

code blocks, use space instead of tabs

2311ae8

Use React fragment for 2 consecutive images

0a2b794

update prismjs

0e545b2

slorber commented Aug 25, 2023

View reviewed changes

slorber marked this pull request as ready for review August 25, 2023 13:15

slorber changed the title ~~More docs fixes preparing for Docusaurus v3~~ chore: prepare docs for Docusaurus v3 upgrade - 2nd iteration Aug 25, 2023

slorber mentioned this pull request Aug 25, 2023

Upgrade React-Native website to Docusaurus v3 #3780

Merged

elicwhite self-assigned this Sep 1, 2023

elicwhite self-requested a review September 1, 2023 21:44

elicwhite merged commit b832016 into facebook:main Sep 1, 2023

slorber mentioned this pull request Sep 2, 2023

chore: prepare docs for Docusaurus v3 upgrade - 3rd iteration #3843

Merged

Conversation

slorber commented Aug 25, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Aug 25, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for react-native ready!

Uh oh!

slorber left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elicwhite commented Sep 1, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

slorber commented Aug 25, 2023 •

edited

Loading

netlify bot commented Aug 25, 2023 •

edited

Loading