docs: add docs for nav

docs/.vitepress/config.ts

@@ -77,6 +77,7 @@ function sidebarGuide() {
       collapsible: true,
       items: [
         { text: 'Introduction', link: '/guide/theme-introduction' },
+        { text: 'Nav', link: '/guide/theme-nav' },
         { text: 'Layout', link: '/guide/theme-layout' },
         { text: 'Homepage', link: '/guide/theme-homepage' },
         { text: 'Footer', link: '/guide/theme-footer' },

docs/guide/configuration.md

@@ -20,4 +20,4 @@ export default {
 }
 ```
 
-Learn everything about VitePress configuration at [configuration page](../config/introduction).
+Learn everything about VitePress features at [Theme: Introduction](./theme-introduction). You may also find all configuration references [configuration page](../config/introduction).

docs/guide/theme-introduction.md

@@ -1,6 +1,14 @@
 # Theme Introduction
 
-VitePress comes with its own default theme, and provides a way to customize it, or evenr create your own theme. At this page, we'll go through the basics of theme customizations.
+VitePress comes with its default theme providing many features out of the box. Learn more about each feature on its dedicated page listed below.
+
+- [Nav](./theme-nav)
+- [Layout](./theme-layout)
+- [Homepage](./theme-homepage)
+- [Footer](./theme-footer)
+- [Carbon Ads](./theme-carbon-ads)
+
+If you don't find the features you're looking for, or you would rather create your own theme, you may customize VitePress to fit your requirements.
 
 ## Using a Custom Theme
 
@@ -121,7 +129,7 @@ See [default theme CSS variables](https://github.com/vuejs/vitepress/blob/main/s
 
 ### Layout Slots
 
-The default theme's `<Layout/>` component has a few slots that can be used to inject content at certain locations of the page. Here's an example of injecting a component into the top of the sidebar:
+The default theme's `<Layout/>` component has a few slots that can be used to inject content at certain locations of the page. Here's an example of injecting a component into the before outline:
 
 ```js
 // .vitepress/theme/index.js
@@ -146,7 +154,7 @@ const { Layout } = DefaultTheme
 
 <template>
   <Layout>
-    <template #sidebar-top>
+    <template #aside-outline-before>
       My custom sidebar top content
     </template>
   </Layout>

docs/guide/theme-layout.md

@@ -4,7 +4,7 @@ layout: doc
 
 # Layout
 
-You may switch the of each page by setting `layout` option to the page [frontmatter](./frontmatter). There are 3 layout options, `doc`, `page`, and `home`. If don't specify the `layout` otpion, then the page is treated as option set to `doc`.
+You may choose the page layout by setting `layout` option to the page [frontmatter](./frontmatter). There are 3 layout options, `doc`, `page`, and `home`. If nothing is specified, then the page is treated as `doc` page.
 
 ```yaml
 ---
@@ -27,7 +27,7 @@ It also provides documentation specific features listed below. These features ar
 
 ## Page Layout
 
-Option `page` is treated as "blank page". The Markdown will still be parsed, and all of the [Markdown Extensions](./markdown-extensions) work as same as `doc` layout, but it wouldn't apply default styling.
+Option `page` is treated as "blank page". The Markdown will still be parsed, and all of the [Markdown Extensions](./markdown-extensions) work as same as `doc` layout, but it wouldn't get any default stylings.
 
 The page layout will let you style everything by you without VitePress theme affecting the markup. This is useful when you want to create your own custom page.
 
@@ -35,4 +35,4 @@ Note that even in this layout, sidebar will still show up if the page has a matc
 
 ## Home Layout
 
-Option `home` will generate templated "Home Page". In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit [Theme: Home Page](./theme-homepage) for more details.
+Option `home` will generate templated "Homepage". In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit [Theme: Home Page](./theme-homepage) for more details.

docs/guide/theme-nav.md

@@ -0,0 +1,164 @@
+# Nav
+
+The Nav is the navigation bar displayed on top of the page. It contains the site title, global menu links, etc.
+
+## Site Title and Logo
+
+By default, nav shows the title of the site refferencing [`config.title`](../config/app-configs.html#title) value. If you would like to change what's displayed on nav, you may define custom text in `themeConfig.siteTitle` option.
+
+```js
+export default {
+  themeConfig: {
+    siteTitle: 'My Custom Title'
+  }
+}
+```
+
+If you have a logo for your site, you can display it by passing in the path to the image. You should place the logo within `public` directly, and define the absolute path to it.
+
+```js
+export default {
+  themeConfig: {
+    logo: '/my-logo.svg'
+  }
+}
+```
+
+When adding a logo, it gets displayed along with the site title. If your logo is all you need and if you would like to hide the site title text, set `false` to the `siteTitle` option.
+
+```js
+export default {
+  themeConfig: {
+    logo: '/my-logo.svg',
+    siteTitle: false
+  }
+}
+```
+
+## Navigation Links
+
+You may define `themeConfig.nav` option to add links to your nav.
+
+```js
+export default {
+  themeConfig: {
+    nav: [
+      { text: 'Guide', link: '/guide' },
+      { text: 'Configs', link: '/configs' },
+      { text: 'Changelog', link: 'https://github.com/...' }
+    ]
+  }
+}
+```
+
+The `text` is the actual text displayed in nav, and the `link` is the link that will be navigated to when the text is clicked. For the link, set path to the actual file without `.md` prefix, and alsways start with `/`.
+
+Nav links can also be dropdown menus. To do this, set `items` key on link option.
+
+```js
+export default {
+  themeConfig: {
+    nav: [
+      { text: 'Guide', link: '/guide' },
+      {
+        text: 'Dropdown Menu',
+        items: [
+          { text: 'Item A', link: '/item-1' },
+          { text: 'Item B', link: '/item-2' },
+          { text: 'Item C', link: '/item-3' }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Note that dropdown menu title (`Dropdown Menu` in the above example) can not have `link` property since it becomes a button to open dropdown dialog.
+
+You may further add "sections" to the dropdown menu items as well by passing in more nested items.
+
+```js
+export default {
+  themeConfig: {
+    nav: [
+      { text: 'Guide', link: '/guide' },
+      {
+        text: 'Dropdown Menu',
+        items: [
+          {
+            // Title for the section.
+            text: 'Section A Title',
+            items: [
+              { text: 'Section A Item A', link: '...' },
+              { text: 'Section B Item B', link: '...' }
+            ]
+          }
+        ]
+      },
+      {
+        text: 'Dropdown Menu',
+        items: [
+          {
+            // You may also omit the title.
+            items: [
+              { text: 'Section A Item A', link: '...' },
+              { text: 'Section B Item B', link: '...' }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Customize link's "active" state
+
+Nav menu items will be highlighted when the current page is under the matching path. if you would like to customize the path to be mathced, define `activeMatch` property and regex as a string value.
+
+```js
+export default {
+  themeConfig: {
+    nav: [
+      // This link gets active state when the user is
+      // on `/config/` path.
+      {
+        text: 'Guide',
+        link: '/guide',
+        activeMatch: '/config/'
+      }
+    ]
+  }
+}
+```
+
+::: warning
+`activeMatch` is expected to be a regex string, but you must define it as a string. We can't use actual RegExp object here because it isn't serializable during the build time.
+:::
+
+## Social Links
+
+You may define `socialLinks` option to show your social account links with icons.
+
+```js
+export default {
+  themeConfig: {
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
+      { icon: 'twitter', link: '...' },
+      { icon: 'discord', link: '...' }
+    ]
+  }
+}
+```
+
+The list of supported icons are shown below.
+
+- `discord`
+- `facebook`
+- `github`
+- `instagram`
+- `linkedin`
+- `slack`
+- `twitter`
+- `youtube`