Document automatic linking

Author: satya164

versioned_docs/version-7.x/configuring-links.md

@@ -4,6 +4,9 @@ title: Configuring links
 sidebar_label: Configuring links
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 In this guide, we will configure React Navigation to handle external links. This is necessary if you want to:
 
 1. Handle deep links in React Native apps on Android and iOS
@@ -12,11 +15,45 @@ In this guide, we will configure React Navigation to handle external links. This
 
 Make sure that you have [configured deep links](deep-linking.md) in your app before proceeding. If you have an Android or iOS app, remember to specify the [`prefixes`](navigation-container.md#linkingprefixes) option.
 
+<Tabs groupId="config" queryString="config">
+<TabItem value="static" label="Static" default>
+
+The [`Navigation`](static-configuration.md#createstaticnavigation) component accepts a [`linking`](static-configuration.md#differences-in-the-linking-prop) prop that makes it easier to handle incoming links:
+
+```js
+import { createStaticNavigation } from '@react-navigation/native';
+
+// highlight-start
+const linking = {
+  enabled: 'auto' /* Automatically generate paths for all screens */,
+  prefixes: [
+    /* your linking prefixes */
+  ],
+};
+// highlight-end
+
+function App() {
+  return (
+    <Navigation
+      // highlight-next-line
+      linking={linking}
+      fallback={<Text>Loading...</Text>}
+    />
+  );
+}
+
+const Navigation = createStaticNavigation(RootStack);
+```
+
+</TabItem>
+<TabItem value="dynamic" label="Dynamic">
+
 The `NavigationContainer` accepts a [`linking`](navigation-container.md#linking) prop that makes it easier to handle incoming links. The 2 of the most important properties you can specify in the `linking` prop are `prefixes` and `config`:
 
 ```js
 import { NavigationContainer } from '@react-navigation/native';
 
+// highlight-start
 const linking = {
   prefixes: [
     /* your linking prefixes */
@@ -25,16 +62,24 @@ const linking = {
     /* configuration for matching screens with paths */
   },
 };
+// highlight-end
 
 function App() {
   return (
-    <NavigationContainer linking={linking} fallback={<Text>Loading...</Text>}>
+    <NavigationContainer
+      // highlight-next-line
+      linking={linking}
+      fallback={<Text>Loading...</Text>}
+    >
       {/* content */}
     </NavigationContainer>
   );
 }
 ```
 
+</TabItem>
+</Tabs>
+
 When you specify the `linking` prop, React Navigation will handle incoming links automatically. On Android and iOS, it'll use React Native's [`Linking` module](https://reactnative.dev/docs/linking) to handle incoming links, both when the app was opened with the link, and when new links are received when the app is open. On the Web, it'll use the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to sync the URL with the browser.
 
 :::warning
@@ -43,7 +88,7 @@ Currently there seems to be bug ([facebook/react-native#25675](https://github.co
 
 :::
 
-You can also pass a [`fallback`](navigation-container.md#fallback) prop to `NavigationContainer` which controls what's displayed when React Navigation is trying to resolve the initial deep link URL.
+You can also pass a [`fallback`](navigation-container.md#fallback) prop that controls what's displayed when React Navigation is trying to resolve the initial deep link URL.
 
 ## Prefixes
 
@@ -69,7 +114,7 @@ const linking = {
 };
 ```
 
-### Filtering certain paths
+## Filtering certain paths
 
 Sometimes we may not want to handle all incoming links. For example, we may want to filter out links meant for authentication (e.g. `expo-auth-session`) or other purposes instead of navigating to a specific screen.
 
@@ -85,7 +130,7 @@ const linking = {
 
 This is not supported on Web as we always need to handle the URL of the page.
 
-### Apps under subpaths
+## Apps under subpaths
 
 If your app is hosted under a subpath, you can specify the subpath at the top-level of the `config`. For example, if your app is hosted at `https://mychat.com/app`, you can specify the `path` as `app`:
 

versioned_docs/version-7.x/static-configuration.md

@@ -308,9 +308,35 @@ function App() {
 }
 ```
 
-This component is a wrapper around the `NavigationContainer` component and accepts the [same props and ref as the `NavigationContainer`](navigation-container.md) component. There's however one difference - the `linking` prop accepted by this component doesn't take a `config` property. Instead, the linking config is automatically inferred from the static config.
+This component is a wrapper around the `NavigationContainer` component and accepts the [same props and ref as the `NavigationContainer`](navigation-container.md) component. It is intended to be rendered once at the root of your app similar to how you'd use `NavigationContainer` component.
 
-This is intended to be rendered once at the root of your app similar to how you'd use `NavigationContainer` component.
+### Differences in the `linking` prop
+
+Similar to `NavigationContainer`, the component returned by `createStaticNavigation` also accepts a [`linking`](navigation-container.md#linking) prop. However, there are some key differences:
+
+1. It's not possible to pass a full `config` object to the `linking` prop. It can only accept [`path`](configuring-links.md#apps-under-subpaths) and an [`initialRouteName` for the root navigator](configuring-links.md#rendering-an-initial-route).
+2. The linking config is collected from the [`linking`](#linking) properties specified in the screen configuration.
+3. It's possible to pass `enabled: 'auto'` to automatically generate paths for all leaf screens:
+
+   ```js
+   const Navigation = createStaticNavigation(RootStack);
+
+   const linking = {
+     enabled: 'auto',
+     prefixes: ['https://example.com', 'example://'],
+   };
+
+   function App() {
+     return <Navigation linking={linking} />;
+   }
+   ```
+
+   Automatic path generation works as follows:
+
+   - Screens with an explicit `linking` property are not used for path generation and will be added as-is.
+   - Screen names will be converted from `PascalCase` to `kebab-case` to use as the path (e.g. `NewsFeed` -> `news-feed`).
+   - Unless a screen has explicit empty path (`path: ''`) to use for the homepage, the first leaf screen encountered will be used as the homepage.
+   - Path generation only handles leaf screens, i.e. no path is generated for screens containing nested navigators. It's still possible to specify a path for them with an explicit `linking` property.
 
 ## `createComponentForStaticNavigation`
 

versioned_docs/version-7.x/upgrading-from-6.x.md

@@ -457,8 +457,8 @@ const MyStack = createNativeStackNavigator({
 
 The static configuration API provides the following benefits:
 
-- Simpler type-checking with TypeScript, it's not necessary to specify screens and their params separately.
-- Easier deep linking setup, the linking configuration can be defined next to the screen.
+- **Simpler type-checking with TypeScript**: It's not necessary to specify screens and their params separately. See [Type checking with TypeScript](typescript.md?config=static) for more details.
+- **Easier deep linking setup**: Paths can be generated automatically. Linking configuration can be defined next to the screen for explicit configuration. See [Configuring links](configuring-links.md?config=static) for more details.
 
 It's also possible to mix the static and dynamic configuration APIs. For example, you can use the static configuration API for the top-level navigators and the dynamic configuration API for the nested navigators where you need more flexibility.