docs: improve linking between doc sections (#1418)

2 files changed, 107 insertions, 61 deletions

diff --git a/docs/.vitepress/api-pages.ts b/docs/.vitepress/api-pages.ts
index dd2df610..4c507f62 100644
--- a/docs/.vitepress/api-pages.ts
+++ b/docs/.vitepress/api-pages.ts
@@ -1,6 +1,7 @@
 // This file is automatically generated.
 // Run 'pnpm run generate:api-docs' to update
 export const apiPages = [
+  { text: 'Overview', link: '/api/' },
   { text: 'Address', link: '/api/address.html' },
   { text: 'Animal', link: '/api/animal.html' },
   { text: 'Color', link: '/api/color.html' },
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index b68ce2c8..65294e08 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -1,11 +1,56 @@
 import { defineConfig } from 'vitepress';
+import { DefaultTheme } from 'vitepress/theme';
 import { apiPages } from './api-pages';
 import { currentVersion, oldVersions } from './versions';
 
+type SidebarGroup = DefaultTheme.SidebarGroup;
+
 const description =
   'Generate massive amounts of fake (but reasonable) data for testing and development.';
 const image = 'https://fakerjs.dev/social-image.png';
 
+function extendSideNav(current: SidebarGroup): SidebarGroup[] {
+  const links: SidebarGroup[] = [
+    {
+      text: 'Guide',
+      items: [
+        {
+          text: 'Usage Guide',
+          link: '/guide/',
+        },
+      ],
+    },
+    {
+      text: 'API',
+      items: [
+        {
+          text: 'API Reference',
+          link: '/api/',
+        },
+      ],
+    },
+    {
+      text: 'About',
+      items: [
+        {
+          text: 'Announcements',
+          link: '/about/announcements',
+        },
+        {
+          text: 'Roadmap',
+          link: '/about/roadmap/',
+        },
+        {
+          text: 'Team',
+          link: '/about/team',
+        },
+      ],
+    },
+  ];
+  links[links.findIndex((group) => group.text === current.text)] = current;
+  return links;
+}
+
 export default defineConfig({
   title: 'Faker',
   description,
@@ -83,7 +128,7 @@ export default defineConfig({
     },
 
     nav: [
-      { text: 'Guide', link: '/guide/' },
+      { text: 'Guide', activeMatch: `^/guide/`, link: '/guide/' },
       {
         text: 'API',
         activeMatch: `^/api/`,
@@ -95,12 +140,17 @@ export default defineConfig({
       },
       {
         text: 'About',
+        activeMatch: `^/about/`,
         items: [
           {
             text: 'Announcements',
             link: '/about/announcements',
           },
           {
+            text: 'Roadmap',
+            link: '/about/roadmap/',
+          },
+          {
             text: 'Team',
             link: '/about/team',
           },
@@ -122,66 +172,61 @@ export default defineConfig({
     ],
 
     sidebar: {
-      '/guide/': [
-        {
-          text: 'Guide',
-          items: [
-            {
-              text: 'Getting Started',
-              link: '/guide/',
-            },
-            {
-              text: 'Usage',
-              link: '/guide/usage',
-            },
-            {
-              text: 'Localization',
-              link: '/guide/localization',
-            },
-            {
-              text: 'Upgrading to v7',
-              link: '/guide/upgrading',
-            },
-          ],
-        },
-      ],
-      '/api/': [
-        {
-          text: 'API',
-          items: apiPages,
-        },
-      ],
-      '/about/': [
-        {
-          text: 'About',
-          items: [
-            {
-              text: 'Announcements',
-              link: '/about/announcements',
-              items: [
-                { text: '2022-09-08', link: '/about/announcements/2022-09-08' },
-                { text: '2022-01-14', link: '/about/announcements/2022-01-14' },
-              ],
-            },
-            {
-              text: 'Roadmap',
-              link: '/about/roadmap/',
-              items: [
-                { text: 'v8 - Make Faker Handier', link: '/about/roadmap/v8' },
-                {
-                  text: 'v7 - Cleanup & Improvements',
-                  link: '/about/roadmap/v7',
-                },
-                { text: 'v6 - Continue Faker', link: '/about/roadmap/v6' },
-              ],
-            },
-            {
-              text: 'Team',
-              link: '/about/team',
-            },
-          ],
-        },
-      ],
+      '/guide/': extendSideNav({
+        text: 'Guide',
+        items: [
+          {
+            text: 'Getting Started',
+            link: '/guide/',
+          },
+          {
+            text: 'Usage',
+            link: '/guide/usage',
+          },
+          {
+            text: 'Localization',
+            link: '/guide/localization',
+          },
+          {
+            text: 'Upgrading to v7',
+            link: '/guide/upgrading',
+          },
+        ],
+      }),
+      '/api/': extendSideNav({
+        text: 'API',
+        items: apiPages,
+      }),
+
+      '/about/': extendSideNav({
+        text: 'About',
+        items: [
+          {
+            text: 'Announcements',
+            link: '/about/announcements',
+            items: [
+              { text: '2022-09-08', link: '/about/announcements/2022-09-08' },
+              { text: '2022-01-14', link: '/about/announcements/2022-01-14' },
+            ],
+          },
+          {
+            text: 'Roadmap',
+            link: '/about/roadmap/',
+            items: [
+              { text: 'v8 - Make Faker Handier', link: '/about/roadmap/v8' },
+              {
+                text: 'v7 - Cleanup & Improvements',
+                link: '/about/roadmap/v7',
+              },
+              { text: 'v6 - Continue Faker', link: '/about/roadmap/v6' },
+            ],
+          },
+          {
+            text: 'Team',
+            link: '/about/team',
+          },
+        ],
+      }),
     },
   },
 });