docs: rewrite the Named Routes page (#2176)

* docs: rewrite the Named Routes page

* Update packages/docs/guide/essentials/named-routes.md [skip ci]

---------

Co-authored-by: Eduardo San Martin Morote <posva@users.noreply.github.com>

diff --git a/packages/docs/.vitepress/config/en.ts b/packages/docs/.vitepress/config/en.ts
index 70042ff08fe68ed1c668977e86732a742326ddd3..98994e1a95df7dd70adf49dd4a77bd6c36d12a73 100644 (file)
--- a/packages/docs/.vitepress/config/en.ts
+++ b/packages/docs/.vitepress/config/en.ts
@@ -84,6 +84,10 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
               text: "Routes' Matching Syntax",
               link: '/guide/essentials/route-matching-syntax.html',
             },
+            {
+              text: 'Named Routes',
+              link: '/guide/essentials/named-routes.html',
+            },
             {
               text: 'Nested Routes',
               link: '/guide/essentials/nested-routes.html',
@@ -92,10 +96,6 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
               text: 'Programmatic Navigation',
               link: '/guide/essentials/navigation.html',
             },
-            {
-              text: 'Named Routes',
-              link: '/guide/essentials/named-routes.html',
-            },
             {
               text: 'Named Views',
               link: '/guide/essentials/named-views.html',

diff --git a/packages/docs/guide/essentials/named-routes.md b/packages/docs/guide/essentials/named-routes.md
index 51d1cda1e5ad957f7cd7d9b7c3c014aba2922e7c..d1e27aae7c5d0284c960376d23775fdadc563eff 100644 (file)
--- a/packages/docs/guide/essentials/named-routes.md
+++ b/packages/docs/guide/essentials/named-routes.md
@@ -5,39 +5,41 @@
   title="Learn about the named routes"
 />
 
-Alongside the `path`, you can provide a `name` to any route. This has the following advantages:
-
-- No hardcoded URLs
-- Automatic encoding/decoding of `params`
-- Prevents you from having a typo in the url
-- Bypassing path ranking (e.g. to display a )
+When creating a route, we can optionally give the route a `name`:
 
 ```js
 const routes = [
   {
     path: '/user/:username',
-    name: 'user',
+    name: 'profile', // [!code highlight]
     component: User
   }
 ]
 ```
 
-To link to a named route, you can pass an object to the `router-link` component's `to` prop:
+We can then use the `name` instead of the `path` when passing the `to` prop to `<router-link>`:
 
 ```vue-html
-<router-link :to="{ name: 'user', params: { username: 'erina' }}">
-  User
+<router-link :to="{ name: 'profile', params: { username: 'erina' } }">
+  User profile
 </router-link>
 ```
 
-This is the exact same object used programmatically with `router.push()`:
+The example above would create a link to `/user/erina`.
 
-```js
-router.push({ name: 'user', params: { username: 'erina' } })
-```
+- [See it in the Playground](https://play.vuejs.org/#eNqtVVtP2zAU/itWNqlFauNNIB6iUMEQEps0NjH2tOzBtKY1JLZlO6VTlP++4+PcelnFwyRofe7fubaKCiZk/GyjJBKFVsaRiswNZ45faU1q8mRUQUbrko8yuaPwlRfK/LkV1sHXpGHeq9JxMzScGmT19t5xkMaUaR1vOb9VBe+kntgWXz2Cs06O1LbCTwvRW7knGnEm50paRwIYcrEFd1xlkpBVyCQ5lN74ZOJV0Nom5JcnCFRCM7dKyIiOJkSygsNzBZiBmivAI7l0SUipRvuhCfPge7uWHBiGZPctS0iLJv7T2/YutFFPIt+JjgUJPn7DZ32CtWg7PIZ/4BASg7txKE6gC1VKNx69gw6NTqJJ1HQK5iR1vNA52M+8Yrr6OLuD+AuCtbQpBQYK9Oy6NAZAhLI1KKuKvEc69jSp65Tqw/oh3V7f00P9MsdveOWiecE75DDNhXwhiVMXWVRttYbUWdRpE2xOZ0sHxq1v2jl/a5jQyZ042Mv/HKjvt2aGFTCXFWmnAsTcCMkAxw4SHIjG9E2AUtpUusWyFvyVUGCltBsFmJB2W/dHZCHWswdYLwJ/XiulnrNr323zcQeodthDuAHTgmm4aEqCH1zsrBHYLIISheyyqD9Nnp1FK+e0TSgtpX5ZxrBBtNe4PItP4w8Q07oBN+a2mD4a9erPzDN4bzY1iy5BiS742imV2ynT4l8h9hQvz+Pz+COU/pGCdyrkgm/Qt3ddw/5Cms7CLXsSy50k/dJDT8037QTcuq1kWZ6r1y/Ic6bkHdD5is9fDvCf7SZA/m44ZLfmg+QcM0vugvjmxx3fwLsTFmpRwlwdE95zq/LSYwxqn0q5ANgDPUT7GXsm5PLB3mwcl7ZNygPFaqA+NvL6SOo93NP4bFDF9sfh+LThtgxvkF80fyxxy/Ac7U9i/RcYNWrd).
+
+Using a `name` has various advantages:
 
-In both cases, the router will navigate to the path `/user/erina`.
+- No hardcoded URLs.
+- Automatic encoding of `params`.
+- Avoids URL typos.
+- Bypassing path ranking, e.g. to display a lower-ranked route that matches the same path.
 
-Full example [here](https://github.com/vuejs/vue-router/blob/dev/examples/named-routes/app.js).
+Each name **must be unique** across all routes. If you add the same name to multiple routes, the router will only keep the last one. You can read more about this [in the Dynamic Routing](../advanced/dynamic-routing#Removing-routes) section.
 
-Each name **must be unique** across all routes. If you add the same name to multiple routes, the router will only keep the last one. You can read more about this [in the Dynamic Routing](../advanced/dynamic-routing.md#Removing-routes) section.
+There are various other parts of Vue Router that can be passed a location, e.g. the methods `router.push()` and `router.replace()`. We'll go into more detail about those methods in the guide to [programmatic navigation](./navigation). Just like the `to` prop, these methods also support passing a location by `name`:
+
+```js
+router.push({ name: 'profile', params: { username: 'erina' } })
+```