From 5ebee75a525d09dbfc20b12b9520ef1fae060157 Mon Sep 17 00:00:00 2001
From: Evan You <yyx990803@gmail.com>
Date: Thu, 2 Mar 2023 16:36:20 +0800
Subject: [PATCH] docs: restructure

---
 docs/.vitepress/config.ts                     |  74 +++++-----
 docs/config/introduction.md                   |  76 -----------
 docs/guide/asset-handling.md                  |   2 +-
 docs/guide/configuration.md                   |  27 ----
 ...customization-intro.md => custom-theme.md} |   0
 docs/guide/{deploying.md => deploy.md}        |   4 +-
 docs/guide/dynamic-routes.md                  |   0
 docs/guide/extending-default-theme.md         |   0
 docs/guide/frontmatter.md                     |   2 +-
 docs/guide/getting-started.md                 |  34 ++++-
 docs/guide/i18n.md                            |   2 +-
 docs/guide/markdown.md                        |   6 +-
 docs/guide/migration-from-vitepress-0.md      |   2 +-
 docs/guide/routing.md                         |   6 +-
 docs/guide/theme-nav.md                       |   6 +-
 docs/guide/theme-sidebar.md                   |   2 +-
 docs/guide/theme-team-page.md                 |   2 +-
 docs/guide/using-vue.md                       |   8 +-
 docs/index.md                                 |   2 +-
 .../default-theme-config.md}                  |   0
 .../frontmatter-config.md                     |   8 +-
 .../index.md => reference/runtime-api.md}     |   4 +-
 .../site-config.md}                           | 126 ++++++++++++++----
 package.json                                  |   5 +-
 24 files changed, 196 insertions(+), 202 deletions(-)
 delete mode 100644 docs/config/introduction.md
 delete mode 100644 docs/guide/configuration.md
 rename docs/guide/{customization-intro.md => custom-theme.md} (100%)
 rename docs/guide/{deploying.md => deploy.md} (98%)
 create mode 100644 docs/guide/dynamic-routes.md
 create mode 100644 docs/guide/extending-default-theme.md
 rename docs/{config/theme-config.md => reference/default-theme-config.md} (100%)
 rename docs/{config => reference}/frontmatter-config.md (86%)
 rename docs/{api/index.md => reference/runtime-api.md} (92%)
 rename docs/{config/app-config.md => reference/site-config.md} (80%)

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index c53710e0..ff598e8e 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -25,8 +25,7 @@ export default defineConfig({
 
     sidebar: {
       '/guide/': sidebarGuide(),
-      '/config/': sidebarConfig(),
-      '/api/': sidebarGuide()
+      '/reference/': sidebarReference()
     },
 
     editLink: {
@@ -60,14 +59,9 @@ function nav() {
   return [
     { text: 'Guide', link: '/guide/what-is-vitepress', activeMatch: '/guide/' },
     {
-      text: 'Config Reference',
-      link: '/config/introduction',
-      activeMatch: '/config/'
-    },
-    {
-      text: 'Runtime API',
-      link: '/api/',
-      activeMatch: '/api/'
+      text: 'Reference',
+      link: '/reference/site-config',
+      activeMatch: '/reference/'
     },
     {
       text: pkg.version,
@@ -93,9 +87,8 @@ function sidebarGuide() {
       items: [
         { text: 'What is VitePress?', link: '/guide/what-is-vitepress' },
         { text: 'Getting Started', link: '/guide/getting-started' },
-        { text: 'Configuration', link: '/guide/configuration' },
         { text: 'Routing', link: '/guide/routing' },
-        { text: 'Deploying', link: '/guide/deploying' }
+        { text: 'Deploy', link: '/guide/deploy' }
       ]
     },
     {
@@ -113,45 +106,48 @@ function sidebarGuide() {
       text: 'Customization',
       collapsed: false,
       items: [
-        //         { text: 'Default Theme', link: '/guide/default-theme' },
-        //         {
-        //           text: 'Extending the Default Theme',
-        //           link: '/guide/customization-extending-default-theme'
-        //         },
-        { text: 'Building a Custom Theme', link: '/guide/customization-intro' },
         {
-          text: 'Runtime API',
-          link: '/api/'
+          text: 'Extending the Default Theme',
+          link: '/guide/extending-default-theme'
         },
-        { text: 'Build-Time Data Loading', link: '/guide/data-loading' }
+        { text: 'Building a Custom Theme', link: '/guide/custom-theme' },
+        { text: 'Build-Time Data Loading', link: '/guide/data-loading' },
+        { text: 'Dynamic Routes', link: '/guide/dynamic-routes' }
       ]
     },
+    // {
+    //   text: 'Migrations',
+    //   collapsed: false,
+    //   items: [
+    //     {
+    //       text: 'Migration from VuePress',
+    //       link: '/guide/migration-from-vuepress'
+    //     },
+    //     {
+    //       text: 'Migration from VitePress 0.x',
+    //       link: '/guide/migration-from-vitepress-0'
+    //     }
+    //   ]
+    // },
     {
-      text: 'Migrations',
-      collapsed: false,
-      items: [
-        {
-          text: 'Migration from VuePress',
-          link: '/guide/migration-from-vuepress'
-        },
-        {
-          text: 'Migration from VitePress 0.x',
-          link: '/guide/migration-from-vitepress-0'
-        }
-      ]
+      text: 'Config & API Reference',
+      link: '/reference/site-config'
     }
   ]
 }
 
-function sidebarConfig() {
+function sidebarReference() {
   return [
     {
-      text: 'Config Reference',
+      text: 'Reference',
       items: [
-        { text: 'Introduction', link: '/config/introduction' },
-        { text: 'App Config', link: '/config/app-config' },
-        { text: 'Default Theme Config', link: '/config/theme-config' },
-        { text: 'Frontmatter Config', link: '/config/frontmatter-config' }
+        { text: 'Site Config', link: '/reference/site-config' },
+        {
+          text: 'Default Theme Config',
+          link: '/reference/default-theme-config'
+        },
+        { text: 'Frontmatter Config', link: '/reference/frontmatter-config' },
+        { text: 'Runtime API', link: '/reference/runtime-api' }
       ]
     }
   ]
diff --git a/docs/config/introduction.md b/docs/config/introduction.md
deleted file mode 100644
index f70829d1..00000000
--- a/docs/config/introduction.md
+++ /dev/null
@@ -1,76 +0,0 @@
-# Introduction
-
-Place your configuration file at `.vitepress/config.js`. This is where all VitePress-specific files will be placed.
-
-```
-.
-├─ docs
-│  ├─ .vitepress
-│  │  └─ config.js
-│  └─ index.md
-└─ package.json
-```
-
-::: tip
-You can also use any of `.ts`, `.cjs`, `.mjs`, `.cts`, `.mts` as the config file extension.
-:::
-
-VitePress comes with 2 types of configuration. One is the [App Config](./app-config) which configures the site's fundamental features such as setting title of the site, or customize how markdown parser works. Second is the [Theme Config](./theme-config) which configures the theme of the site, for example, adding a sidebar, or add features such as "Edit this page on GitHub" link.
-
-There's also another configuration you may do in [Frontmatter](./frontmatter-config). Frontmatter config can override global config defined in App Config or Theme Config for that specific page. However, there're several options that are only available at frontmatter as well.
-
-Please refer to the corresponding config page to learn more.
-
-## Config Intellisense
-
-Since VitePress ships with TypeScript typings, you can leverage your IDE's intellisense with jsdoc type hints:
-
-```js
-/**
- * @type {import('vitepress').UserConfig}
- */
-const config = {
-  // ...
-}
-
-export default config
-```
-
-Alternatively, you can use the `defineConfig` helper at which should provide intellisense without the need for jsdoc annotations:
-
-```js
-import { defineConfig } from 'vitepress'
-
-export default defineConfig({
-  // ...
-})
-```
-
-VitePress also directly supports TS config files. You can use `.vitepress/config.ts` with the `defineConfig` helper as well.
-
-## Typed Theme Config
-
-By default, `defineConfig` helper leverages the theme config type from default theme:
-
-```ts
-import { defineConfig } from 'vitepress'
-
-export default defineConfig({
-  themeConfig: {
-    // Type is `DefaultTheme.Config`
-  }
-})
-```
-
-If you use a custom theme and want type checks for the theme config, you'll need to use `defineConfigWithTheme` instead, and pass the config type for your custom theme via a generic argument:
-
-```ts
-import { defineConfigWithTheme } from 'vitepress'
-import { ThemeConfig } from 'your-theme'
-
-export default defineConfigWithTheme<ThemeConfig>({
-  themeConfig: {
-    // Type is `ThemeConfig`
-  }
-})
-```
diff --git a/docs/guide/asset-handling.md b/docs/guide/asset-handling.md
index 132b6b6e..8ec2ac24 100644
--- a/docs/guide/asset-handling.md
+++ b/docs/guide/asset-handling.md
@@ -45,7 +45,7 @@ However, if you are authoring a theme component that links to assets dynamically
 <img :src="theme.logoPath" />
 ```
 
-In this case it is recommended to wrap the path with the [`withBase` helper](/api/#withbase) provided by VitePress:
+In this case it is recommended to wrap the path with the [`withBase` helper](/reference/runtime-api#withbase) provided by VitePress:
 
 ```vue
 <script setup>
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
deleted file mode 100644
index d65bfdb6..00000000
--- a/docs/guide/configuration.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# Configuration
-
-Without any configuration, the page is pretty minimal, and the user has no way to navigate around the site. To customize your site, let's first create a `.vitepress` directory inside your docs directory. This is where all VitePress-specific files will be placed. Your project structure is probably like this:
-
-```
-.
-├─ docs
-│  ├─ .vitepress
-│  │  └─ config.js
-│  └─ index.md
-└─ package.json
-```
-
-The essential file for configuring a VitePress site is `.vitepress/config.js`, which should export a JavaScript object:
-
-```js
-export default {
-  title: 'VitePress',
-  description: 'Just playing around.'
-}
-```
-
-In the above example, the site will have the title of `VitePress`, and `Just playing around.` as the description meta tag.
-
-Learn everything about VitePress features at [Theme: Introduction](./customization-intro) to find how to configure specific features within this config file.
-
-You may also find all configuration references at [Config Reference](../config/introduction).
diff --git a/docs/guide/customization-intro.md b/docs/guide/custom-theme.md
similarity index 100%
rename from docs/guide/customization-intro.md
rename to docs/guide/custom-theme.md
diff --git a/docs/guide/deploying.md b/docs/guide/deploy.md
similarity index 98%
rename from docs/guide/deploying.md
rename to docs/guide/deploy.md
index 4f5d76de..904924c5 100644
--- a/docs/guide/deploying.md
+++ b/docs/guide/deploy.md
@@ -1,4 +1,4 @@
-# Deploying
+# Deploy Your VitePress Site
 
 The following guides are based on some shared assumptions:
 
@@ -17,7 +17,7 @@ The following guides are based on some shared assumptions:
 
 ::: tip
 
-If your site is to be served at a subdirectory (`https://example.com/subdir/`), then you have to set `'/subdir/'` as the [`base`](../config/app-config#base) in your `docs/.vitepress/config.js`.
+If your site is to be served at a subdirectory (`https://example.com/subdir/`), then you have to set `'/subdir/'` as the [`base`](/reference/site-config#base) in your `docs/.vitepress/config.js`.
 
 **Example:** If you're using Github (or GitLab) Pages and deploying to `user.github.io/repo/`, then set your `base` to `/repo/`.
 
diff --git a/docs/guide/dynamic-routes.md b/docs/guide/dynamic-routes.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/guide/extending-default-theme.md b/docs/guide/extending-default-theme.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/guide/frontmatter.md b/docs/guide/frontmatter.md
index b64a5f54..94e6fef7 100644
--- a/docs/guide/frontmatter.md
+++ b/docs/guide/frontmatter.md
@@ -9,7 +9,7 @@ editLink: true
 ---
 ```
 
-Between the triple-dashed lines, you can set [predefined variables](../config/frontmatter-config), or even create custom ones of your own. These variables can be used via the special <code>$frontmatter</code> variable.
+Between the triple-dashed lines, you can set [predefined variables](/reference/frontmatter-config), or even create custom ones of your own. These variables can be used via the special <code>$frontmatter</code> variable.
 
 Here's an example of how you could use it in your Markdown file:
 
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index 4f759d8b..325f6e3f 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -128,14 +128,40 @@ Then, try to access `http://localhost:5173/getting-started.html` and you should
 
 This is how VitePress works basically. The directory structure corresponds with the URL path. You add files, and just try to access it.
 
+## Configuration
+
+Without any configuration, the page is pretty minimal, and the user has no way to navigate around the site. To customize your site, let's first create a `.vitepress` directory inside your docs directory. This is where all VitePress-specific files will be placed. Your project structure is probably like this:
+
+```
+.
+├─ docs
+│  ├─ .vitepress
+│  │  └─ config.js
+│  └─ index.md
+└─ package.json
+```
+
+The essential file for configuring a VitePress site is `.vitepress/config.js`, which should export a JavaScript object:
+
+```js
+export default {
+  title: 'VitePress',
+  description: 'Just playing around.'
+}
+```
+
+In the above example, the site will have the title of `VitePress`, and `Just playing around.` as the description meta tag.
+
+Learn everything about VitePress features at [Theme: Introduction](./custom-theme) to find how to configure specific features within this config file.
+
+You may also find all configuration references at [Config Reference](/reference/site-config).
+
 ## What's next?
 
 By now, you should have a basic but functional VitePress documentation site. But currently, the user has no way to navigate around the site because it's missing for example sidebar menu we have on this site.
 
-To enable those navigations, we must add some configurations to the site. Head to [configuration guide](./configuration) to learn how to configure VitePress.
-
 If you would like to know more about what you can do within the page, for example, writing markdown contents, or using Vue Component, check out the "Writing" section of the docs. [Markdown guide](./markdown) would be a great starting point.
 
-If you want to know how to customize how the site looks (Theme), and find out the features VitePress's default theme provides, visit [Theme: Introduction](./customization-intro).
+If you want to know how to customize how the site looks (Theme), and find out the features VitePress's default theme provides, check out how to [extend the default theme](./extending-default-theme) or [build a custom theme](./custom-theme).
 
-When your documentation site starts to take shape, be sure to read the [deployment guide](./deploying).
+When your documentation site starts to take shape, be sure to read the [deployment guide](./deploy).
diff --git a/docs/guide/i18n.md b/docs/guide/i18n.md
index 9b78c5fa..ccd5b66a 100644
--- a/docs/guide/i18n.md
+++ b/docs/guide/i18n.md
@@ -75,7 +75,7 @@ However, VitePress won't redirect `/` to `/en/` by default. You'll need to confi
 /*  /en/:splat  302
 ```
 
-**Pro tip:** If using the above approach, you can use `nf_lang` cookie to persist user's language choice. A very basic way to do this is register a watcher inside the [setup](./customization-intro#using-a-custom-theme) function of custom theme:
+**Pro tip:** If using the above approach, you can use `nf_lang` cookie to persist user's language choice. A very basic way to do this is register a watcher inside the [setup](./custom-theme#using-a-custom-theme) function of custom theme:
 
 ```ts
 // docs/.vitepress/theme/index.ts
diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md
index 65541906..abba4466 100644
--- a/docs/guide/markdown.md
+++ b/docs/guide/markdown.md
@@ -281,7 +281,7 @@ export default {
 
 A [list of valid languages](https://github.com/shikijs/shiki/blob/main/docs/languages.md) is available on Shiki's repository.
 
-You may also customize syntax highlight theme in app config. Please see [`markdown` options](../config/app-config#markdown) for more details.
+You may also customize syntax highlight theme in app config. Please see [`markdown` options](/reference/site-config#markdown) for more details.
 
 ## Line Highlighting in Code Blocks
 
@@ -493,7 +493,7 @@ export default {
 }
 ```
 
-Please see [`markdown` options](../config/app-config#markdown) for more details.
+Please see [`markdown` options](/reference/site-config#markdown) for more details.
 
 You can add `:line-numbers` / `:no-line-numbers` mark in your fenced code blocks to override the value set in config.
 
@@ -748,4 +748,4 @@ module.exports = {
 }
 ```
 
-See full list of configurable properties in [Config Reference: App Config](../config/app-config#markdown).
+See full list of configurable properties in [Config Reference: App Config](/reference/site-config#markdown).
diff --git a/docs/guide/migration-from-vitepress-0.md b/docs/guide/migration-from-vitepress-0.md
index b9381c09..ee21616b 100644
--- a/docs/guide/migration-from-vitepress-0.md
+++ b/docs/guide/migration-from-vitepress-0.md
@@ -20,4 +20,4 @@ If you're coming from VitePress 0.x version, there're several breaking changes d
 ## Frontmatter Config
 
 - `home: true` option has changed to `layout: home`. Also, many Homepage related settings have been modified to provide additional features. See [Home Page guide](./theme-home-page) for details.
-- `footer` option is moved to [`themeConfig.footer`](../config/theme-config#footer).
+- `footer` option is moved to [`themeConfig.footer`](/reference/default-theme-config#footer).
diff --git a/docs/guide/routing.md b/docs/guide/routing.md
index 29280808..6df8799f 100644
--- a/docs/guide/routing.md
+++ b/docs/guide/routing.md
@@ -49,7 +49,7 @@ docs/index.md           -> /
 docs/getting-started.md -> /getting-started.html
 ```
 
-You may also customize the root directory in config file via [`srcDir`](/config/app-config#srcdir) option too. Running `vitepress dev` with the following setting acts same as running `vitepress dev docs` command.
+You may also customize the root directory in config file via [`srcDir`](/reference/site-config#srcdir) option too. Running `vitepress dev` with the following setting acts same as running `vitepress dev docs` command.
 
 ```ts
 export default {
@@ -88,7 +88,7 @@ By default, VitePress generates the final static page files by adding `.html` ex
 └─ index.md
 ```
 
-However, you may also generate a clean URL by setting up [`cleanUrls`](/config/app-config#cleanurls) option.
+However, you may also generate a clean URL by setting up [`cleanUrls`](/reference/site-config#cleanurls) option.
 
 ```ts
 export default {
@@ -120,7 +120,7 @@ packages/pkg-a/src/pkg-a-code.md -> /pkg-a/pkg-a-code.md
 packages/pkg-b/src/pkg-b-code.md -> /pkg-b/pkg-b-code.md
 ```
 
-You may configure the mapping via [`rewrites`](/config/app-config#rewrites) option like this.
+You may configure the mapping via [`rewrites`](/reference/site-config#rewrites) option like this.
 
 ```ts
 export default {
diff --git a/docs/guide/theme-nav.md b/docs/guide/theme-nav.md
index 2c82d649..5c2a92db 100644
--- a/docs/guide/theme-nav.md
+++ b/docs/guide/theme-nav.md
@@ -4,7 +4,7 @@ The Nav is the navigation bar displayed on top of the page. It contains the site
 
 ## Site Title and Logo
 
-By default, nav shows the title of the site referencing [`config.title`](../config/app-config#title) value. If you would like to change what's displayed on nav, you may define custom text in `themeConfig.siteTitle` option.
+By default, nav shows the title of the site referencing [`config.title`](/reference/site-config#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 {
@@ -35,7 +35,7 @@ export default {
 }
 ```
 
-You can also pass an object as logo if you want to add `alt` attribute or customize it based on dark/light mode. Refer [`themeConfig.logo`](../config/theme-config#logo) for details.
+You can also pass an object as logo if you want to add `alt` attribute or customize it based on dark/light mode. Refer [`themeConfig.logo`](/reference/default-theme-config#logo) for details.
 
 ## Navigation Links
 
@@ -159,4 +159,4 @@ export default {
 
 ## Social Links
 
-Refer [`socialLinks`](../config/theme-config#sociallinks).
+Refer [`socialLinks`](/reference/default-theme-config#sociallinks).
diff --git a/docs/guide/theme-sidebar.md b/docs/guide/theme-sidebar.md
index 67d61dd8..d46da745 100644
--- a/docs/guide/theme-sidebar.md
+++ b/docs/guide/theme-sidebar.md
@@ -1,6 +1,6 @@
 # Sidebar
 
-The sidebar is the main navigation block for your documentation. You can configure the sidebar menu in [`themeConfig.sidebar`](/config/theme-config#sidebar).
+The sidebar is the main navigation block for your documentation. You can configure the sidebar menu in [`themeConfig.sidebar`](/reference/default-theme-config#sidebar).
 
 ```js
 export default {
diff --git a/docs/guide/theme-team-page.md b/docs/guide/theme-team-page.md
index 0d0aa880..b13bff51 100644
--- a/docs/guide/theme-team-page.md
+++ b/docs/guide/theme-team-page.md
@@ -207,7 +207,7 @@ interface TeamMember {
 
   // Social links. e.g. GitHub, Twitter, etc. You may pass in
   // the Social Links object here.
-  // See: https://vitepress.vuejs.org/config/theme-config.html#sociallinks
+  // See: https://vitepress.vuejs.org/reference/default-theme-config.html#sociallinks
   links?: SocialLink[]
 
   // URL for the sponsor page for the member.
diff --git a/docs/guide/using-vue.md b/docs/guide/using-vue.md
index 9850bfce..484d304c 100644
--- a/docs/guide/using-vue.md
+++ b/docs/guide/using-vue.md
@@ -36,7 +36,7 @@ Directives also work:
 
 ### Access to Site & Page Data
 
-You can use the [`useData` helper](/api/#usedata) in a `<script>` block and expose the data to the page.
+You can use the [`useData` helper](/reference/runtime-api#usedata) in a `<script>` block and expose the data to the page.
 
 **Input**
 
@@ -104,7 +104,7 @@ This is a .md using a custom component
 
 ### Registering global components in the theme
 
-If the components are going to be used across several pages in the docs, they can be registered globally in the theme (or as part of extending the default VitePress theme). Check out the [Customization Guide](./customization-intro) for more information.
+If the components are going to be used across several pages in the docs, they can be registered globally in the theme (or as part of extending the default VitePress theme). Check out the [Customization Guide](./custom-theme) for more information.
 
 In `.vitepress/theme/index.js`, the `enhanceApp` function receives the Vue `app` instance so you can [register components](https://vuejs.org/guide/components/registration.html) as you would do in a regular Vue application.
 
@@ -198,7 +198,7 @@ export default {
 
 ## Built-In Components
 
-VitePress provides Built-In Vue Components like `ClientOnly`, check out the [Global Component Guide](/api/) for more information.
+VitePress provides Built-In Vue Components like `ClientOnly`, check out the [Runtime API Reference](/reference/runtime-api) for more information.
 
 **Also see:**
 
@@ -263,7 +263,7 @@ export default {
 
 ## Using Teleports
 
-Vitepress currently has SSG support for teleports to body only. For other targets, you can wrap them inside the built-in `<ClientOnly>` component or inject the teleport markup into the correct location in your final page HTML through [`postRender` hook](../config/app-config#postrender).
+Vitepress currently has SSG support for teleports to body only. For other targets, you can wrap them inside the built-in `<ClientOnly>` component or inject the teleport markup into the correct location in your final page HTML through [`postRender` hook](/reference/site-config#postrender).
 
 <ModalDemo />
 
diff --git a/docs/index.md b/docs/index.md
index f3344fe3..9d283151 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -19,7 +19,7 @@ hero:
 features:
   - icon: 📝
     title: Focus on Your Content
-    details: Effortlessly create beautiful documentation sites with the feature-rich default theme.
+    details: Effortlessly create beautiful documentation sites with just markdown.
   - icon:
       src: vite.svg
       width: 10
diff --git a/docs/config/theme-config.md b/docs/reference/default-theme-config.md
similarity index 100%
rename from docs/config/theme-config.md
rename to docs/reference/default-theme-config.md
diff --git a/docs/config/frontmatter-config.md b/docs/reference/frontmatter-config.md
similarity index 86%
rename from docs/config/frontmatter-config.md
rename to docs/reference/frontmatter-config.md
index 0a41fbac..96fdfa8f 100644
--- a/docs/config/frontmatter-config.md
+++ b/docs/reference/frontmatter-config.md
@@ -19,7 +19,7 @@ You can access frontmatter by `$frontmatter` helper inside any markdown file.
 
 - Type: `string`
 
-Title for the page. It's same as [config.title](../config/app-config#title), and it overrides the app config.
+Title for the page. It's same as [config.title](/reference/site-config#title), and it overrides the app config.
 
 ```yaml
 ---
@@ -31,7 +31,7 @@ title: VitePress
 
 - Type: `string | boolean`
 
-The suffix for the title. It's same as [config.titleTemplate](../config/app-config#titletemplate), and it overrides the app config.
+The suffix for the title. It's same as [config.titleTemplate](/reference/site-config#titletemplate), and it overrides the app config.
 
 ```yaml
 ---
@@ -44,7 +44,7 @@ titleTemplate: Vite & Vue powered static site generator
 
 - Type: `string`
 
-Description for the page. It's same as [config.description](../config/app-config#description), and it overrides the app config.
+Description for the page. It's same as [config.description](/reference/site-config#description), and it overrides the app config.
 
 ```yaml
 ---
@@ -189,4 +189,4 @@ aside: false
 - Type: `number | [number, number] | 'deep' | false`
 - Default: `2`
 
-The levels of header in the outline to display for the page. It's same as [config.themeConfig.outline](../config/theme-config#outline), and it overrides the theme config.
+The levels of header in the outline to display for the page. It's same as [config.themeConfig.outline](/reference/default-theme-config#outline), and it overrides the theme config.
diff --git a/docs/api/index.md b/docs/reference/runtime-api.md
similarity index 92%
rename from docs/api/index.md
rename to docs/reference/runtime-api.md
index 3981ee99..e9dfae91 100644
--- a/docs/api/index.md
+++ b/docs/reference/runtime-api.md
@@ -66,11 +66,11 @@ interface Router {
 
 - **Type**: `(path: string) => string`
 
-Appends the configured [`base`](/config/app-config#base) to a given URL path. Also see [Base URL](/guide/asset-handling#base-url).
+Appends the configured [`base`](/reference/site-config#base) to a given URL path. Also see [Base URL](/guide/asset-handling#base-url).
 
 ## `<Content />`
 
-The `<Content />` component displays the rendered markdown contents. Useful [when creating your own theme](/guide/customization-intro).
+The `<Content />` component displays the rendered markdown contents. Useful [when creating your own theme](/guide/custom-theme).
 
 ```vue
 <template>
diff --git a/docs/config/app-config.md b/docs/reference/site-config.md
similarity index 80%
rename from docs/config/app-config.md
rename to docs/reference/site-config.md
index 8f69c8b4..ab91fa7c 100644
--- a/docs/config/app-config.md
+++ b/docs/reference/site-config.md
@@ -1,6 +1,28 @@
-# App Config
+---
+outline: deep
+---
+
+# Site Config
+
+Site config is where you can define the global settings of the site. App config options define settings that apply to every VitePress site, regardless of what theme it is using. For example, the base directory or the title of the site.
+
+## Config Resolution
+
+Place your configuration file at `.vitepress/config.js`. This is where all VitePress-specific files will be placed.
+
+```
+.
+├─ docs
+│  ├─ .vitepress
+│  │  └─ config.js
+│  └─ index.md
+└─ package.json
+```
+
+::: tip
+You can also use any of `.ts`, `.cjs`, `.mjs`, `.cts`, `.mts` as the config file extension.
+:::
 
-App config is where you can define the global settings of the site. App config options define settings that apply to every VitePress site, regardless of what theme it is using. For example, the base directory or the title of the site.
 
 ```ts
 export default {
@@ -12,7 +34,63 @@ export default {
 }
 ```
 
-## appearance
+## Config Intellisense
+
+Since VitePress ships with TypeScript typings, you can leverage your IDE's intellisense with jsdoc type hints:
+
+```js
+/**
+ * @type {import('vitepress').UserConfig}
+ */
+const config = {
+  // ...
+}
+
+export default config
+```
+
+Alternatively, you can use the `defineConfig` helper at which should provide intellisense without the need for jsdoc annotations:
+
+```js
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  // ...
+})
+```
+
+VitePress also directly supports TS config files. You can use `.vitepress/config.ts` with the `defineConfig` helper as well.
+
+## Typed Theme Config
+
+By default, `defineConfig` helper leverages the theme config type from default theme:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  themeConfig: {
+    // Type is `DefaultTheme.Config`
+  }
+})
+```
+
+If you use a custom theme and want type checks for the theme config, you'll need to use `defineConfigWithTheme` instead, and pass the config type for your custom theme via a generic argument:
+
+```ts
+import { defineConfigWithTheme } from 'vitepress'
+import { ThemeConfig } from 'your-theme'
+
+export default defineConfigWithTheme<ThemeConfig>({
+  themeConfig: {
+    // Type is `ThemeConfig`
+  }
+})
+```
+
+## Config Options
+
+### appearance
 
 - Type: `boolean | 'dark'`
 - Default: `true`
@@ -31,7 +109,7 @@ export default {
 }
 ```
 
-## base
+### base
 
 - Type: `string`
 - Default: `/`
@@ -46,7 +124,7 @@ export default {
 }
 ```
 
-## description
+### description
 
 - Type: `string`
 - Default: `A VitePress site`
@@ -59,7 +137,7 @@ export default {
 }
 ```
 
-## head
+### head
 
 - Type: `HeadConfig[]`
 - Default: `[]`
@@ -84,7 +162,7 @@ type HeadConfig =
   | [string, Record<string, string>, string]
 ```
 
-## ignoreDeadLinks
+### ignoreDeadLinks
 
 - Type: `boolean | 'localhostLinks'`
 - Default: `false`
@@ -97,7 +175,7 @@ export default {
 }
 ```
 
-## lang
+### lang
 
 - Type: `string`
 - Default: `en-US`
@@ -110,12 +188,12 @@ export default {
 }
 ```
 
-## lastUpdated
+### lastUpdated
 
 - Type: `boolean`
 - Default: `false`
 
-Use git commit to get the timestamp. This option enables the default theme to display the page's last updated time. You can customize the text via [`themeConfig.lastUpdatedText`](theme-config#lastupdatedtext) option.
+Use git commit to get the timestamp. This option enables the default theme to display the page's last updated time. You can customize the text via [`themeConfig.lastUpdatedText`](./default-theme-config#lastupdatedtext) option.
 
 ```ts
 export default {
@@ -123,7 +201,7 @@ export default {
 }
 ```
 
-## markdown
+### markdown
 
 - Type: `MarkdownOption`
 
@@ -195,7 +273,7 @@ interface MarkdownOptions extends MarkdownIt.Options {
 }
 ```
 
-## outDir
+### outDir
 
 - Type: `string`
 - Default: `./.vitepress/dist`
@@ -208,7 +286,7 @@ export default {
 }
 ```
 
-## cacheDir
+### cacheDir
 
 - Type: `string`
 - Default: `./.vitepress/cache`
@@ -221,7 +299,7 @@ export default {
 }
 ```
 
-## srcDir
+### srcDir
 
 - Type: `string`
 - Default: `.`
@@ -234,7 +312,7 @@ export default {
 }
 ```
 
-## title
+### title
 
 - Type: `string`
 - Default: `VitePress`
@@ -247,7 +325,7 @@ export default {
 }
 ```
 
-## titleTemplate
+### titleTemplate
 
 - Type: `string | boolean`
 
@@ -270,7 +348,7 @@ export default {
 }
 ```
 
-## cleanUrls
+### cleanUrls
 
 - Type: `boolean`
 - Default: `false`
@@ -287,7 +365,7 @@ export default {
 Enabling this may require additional configuration on your hosting platform. For it to work, your server must serve `/foo.html` on requesting `/foo` **without a redirect**.
 :::
 
-## rewrites
+### rewrites
 
 - Type: `Record<string, string>`
 
@@ -301,7 +379,7 @@ export default {
 }
 ```
 
-## Build Hooks
+### Build Hooks
 
 VitePress build hooks allow you to add new functionality and behaviors to your website:
 
@@ -310,7 +388,7 @@ VitePress build hooks allow you to add new functionality and behaviors to your w
 - PWA
 - Teleports
 
-### buildEnd
+#### buildEnd
 
 - Type: `(siteConfig: SiteConfig) => Awaitable<void>`
 
@@ -324,7 +402,7 @@ export default {
 }
 ```
 
-### postRender
+#### postRender
 
 - Type: `(context: SSGContext) => Awaitable<SSGContext | void>`
 
@@ -346,7 +424,7 @@ interface SSGContext {
 }
 ```
 
-### transformHead
+#### transformHead
 
 - Type: `(context: TransformContext) => Awaitable<HeadConfig[]>`
 
@@ -376,7 +454,7 @@ interface TransformContext {
 }
 ```
 
-### transformHtml
+#### transformHtml
 
 - Type: `(code: string, id: string, ctx: TransformContext) => Awaitable<string | void>`
 
@@ -394,7 +472,7 @@ export default {
 }
 ```
 
-### transformPageData
+#### transformPageData
 
 - Type: `(pageData: PageData) => Awaitable<Partial<PageData> | { [key: string]: any } | void>`
 
diff --git a/package.json b/package.json
index 00e5d66c..2b4968a5 100644
--- a/package.json
+++ b/package.json
@@ -80,10 +80,7 @@
     "docs-debug": "node --inspect-brk ./bin/vitepress dev docs",
     "docs-build": "run-s build docs-build-only",
     "docs-build-only": "node ./bin/vitepress build docs",
-    "docs-preview": "node ./bin/vitepress preview docs",
-    "docs:dev": "vitepress dev /Users/evan/Vue/vitepress/__tests__/init/temp",
-    "docs:build": "vitepress build /Users/evan/Vue/vitepress/__tests__/init/temp",
-    "docs:preview": "vitepress preview /Users/evan/Vue/vitepress/__tests__/init/temp"
+    "docs-preview": "node ./bin/vitepress preview docs"
   },
   "dependencies": {
     "@docsearch/css": "^3.3.3",