From 3e1239d8c752e3268070eee7060359589b515f78 Mon Sep 17 00:00:00 2001
From: Anthony Fu <anthonyfu117@hotmail.com>
Date: Mon, 15 Nov 2021 20:00:14 +0800
Subject: [PATCH] docs: document `<ClientOnly>` and `<NuxtLink>` (#1856)

---
 .../2.directory-structure/4.components.md     | 34 +++++++++
 .../3.docs/2.directory-structure/9.pages.md   | 76 +++++++++++--------
 docs/yarn.lock                                |  8 +-
 3 files changed, 82 insertions(+), 36 deletions(-)

diff --git a/docs/content/3.docs/2.directory-structure/4.components.md b/docs/content/3.docs/2.directory-structure/4.components.md
index 5df4fc8f44..8dd915a81c 100644
--- a/docs/content/3.docs/2.directory-structure/4.components.md
+++ b/docs/content/3.docs/2.directory-structure/4.components.md
@@ -83,6 +83,40 @@ export default {
 </script>
 ```
 
+## `<ClientOnly>` Component
+
+Nuxt provides the `<ClientOnly>` component for purposely rendering a component only on client-side. To import a component only on the client, register the component in a client-side only plugin.
+
+```html{}[pages/example.vue]
+<template>
+  <div>
+    <Sidebar />
+    <ClientOnly>
+      <!-- this component will only be rendered on client-side -->
+      <Comments />
+    </ClientOnly>
+  </div>
+</template>
+```
+
+Use a slot as fallback until `<ClientOnly>` is mounted on client-side.
+
+```html{}[pages/example.vue]
+<template>
+  <div>
+    <Sidebar />
+    <ClientOnly>
+      <!-- this component will only be rendered on client-side -->
+      <Comments />
+      <template #fallback>
+        <!-- this will be rendered on server-side -->
+        <p>Loading comments...</p>
+      </template>
+    </ClientOnly>
+  </div>
+</template>
+```
+
 ## Library Authors
 
 Making Vue component libraries with automatic tree-shaking and component registration is super easy ✨
diff --git a/docs/content/3.docs/2.directory-structure/9.pages.md b/docs/content/3.docs/2.directory-structure/9.pages.md
index a42176048a..0e31a1d1f5 100644
--- a/docs/content/3.docs/2.directory-structure/9.pages.md
+++ b/docs/content/3.docs/2.directory-structure/9.pages.md
@@ -46,11 +46,41 @@ Navigating to `/users-admins/123` would render:
 admins 123
 ```
 
+## Navigation
+
+To navigate between pages of your app, you should use the  `<NuxtLink>` component. This component is included with Nuxt and therefore you don't have to import it like you do with other components. It is similar to the HTML `<a>` tag except that instead of using a `href="/about"` you use `to="/about"`. If you've used `vue-router` before, you can think of `<NuxtLink>` as a replacement of `<RouterLink>`
+
+A simple link to the `index.vue` page in your `pages` folder:
+
+```html
+<template>
+  <NuxtLink to="/">Home page</NuxtLink>
+</template>
+```
+
+The `<NuxtLink>` component should be used for all internal links. That means for all links to the pages within your site you should use `<NuxtLink>`. The `<a>` tag should be used for all external links. That means if you have links to other websites you should use the `<a>` tag for those.
+
+```html
+<template>
+  <div>
+    <h1>Home page</h1>
+    <NuxtLink to="/about">
+      About (internal link that belongs to the Nuxt App)
+    </NuxtLink>
+    <a href="https://nuxtjs.org">External Link to another page</a>
+  </div>
+</template>
+```
+
+::alert{type="info"}
+If you want to know more about `<RouterLink>`, read the [Vue Router documentation](https://next.router.vuejs.org/api/#router-link) for more information.
+::
+
 ## Nested Routes
 
-We provide a semantic alias for `RouterView`, the `NuxtChild` component, for displaying the children components of a [nested route](https://next.router.vuejs.org/guide/essentials/nested-routes.html).
+We provide a semantic alias for `RouterView`, the `<NuxtChild>` component, for displaying the children components of a [nested route](https://next.router.vuejs.org/guide/essentials/nested-routes.html).
 
-### Example
+Example:
 
 ```bash
 -| pages/
@@ -59,36 +89,7 @@ We provide a semantic alias for `RouterView`, the `NuxtChild` component, for dis
 ---| parent.vue
 ```
 
-To display the `child.vue` component, simply put the `<NuxtChild>` component inside the `parent.vue` component:
-
-```html{}[pages/parent/child.vue]
-<template>
-  <div>
-    <h3>child.vue</h3>
-  </div>
-</template>
-```
-
-```html{}[pages/parent.vue]
-<template>
-  <div>
-    <h1>parent.vue</h1>
-    <NuxtChild />
-  </div>
-</template>
-
-<!-- output -->
-<template>
-  <div>
-    <h1>parent.vue</h1>
-    <div>
-      <h3>child.vue</h3>
-    </div>
-  </div>
-</template>
-```
-
-The example file tree above should generate these routes:
+This file tree will generate these routes:
 
 ```js
 [
@@ -106,3 +107,14 @@ The example file tree above should generate these routes:
   }
 ]
 ```
+
+To display the `child.vue` component, you have to insert the `<NuxtChild>` component inside `pages/parent.vue`:
+
+```html{}[pages/parent.vue]
+<template>
+  <div>
+    <h1>I am the parent view</h1>
+    <NuxtChild :foobar="123" />
+  </div>
+</template>
+```
diff --git a/docs/yarn.lock b/docs/yarn.lock
index 8f757152ec..92a1b4c8ed 100644
--- a/docs/yarn.lock
+++ b/docs/yarn.lock
@@ -10253,10 +10253,10 @@ std-env@^2.2.1, std-env@^2.3.0, std-env@^2.3.1:
   dependencies:
     ci-info "^3.1.1"
 
-std-env@^3.0.0:
-  version "3.0.0"
-  resolved "https://registry.yarnpkg.com/std-env/-/std-env-3.0.0.tgz#8dbd16bd2aadc18992072e2f5839e897f4ee2733"
-  integrity sha512-GoFEqAGzhaexp/T01rIiLOK9LHa6HmVwEUyeU4cwdSnOhfxpw9IMeAFi44SHWbCErEs29qEh7vAOUbtUmoycjA==
+std-env@^3.0.1:
+  version "3.0.1"
+  resolved "https://registry.yarnpkg.com/std-env/-/std-env-3.0.1.tgz#bc4cbc0e438610197e34c2d79c3df30b491f5182"
+  integrity sha512-mC1Ps9l77/97qeOZc+HrOL7TIaOboHqMZ24dGVQrlxFcpPpfCHpH+qfUT7Dz+6mlG8+JPA1KfBQo19iC/+Ngcw==
 
 stream-browserify@^2.0.1:
   version "2.0.2"