docs: improve docs about config and theme (close vuepress#517)

Author: meteorlxy

docs/guide/configuration.md

@@ -20,10 +20,13 @@ The essential file for configuring a VuePress site is `.vuepress/config.js`, whi
 
 ```js
 module.exports = {
+  // site config
   lang: 'en-US',
   title: 'Hello, VuePress!',
   description: 'This is my first VuePress site',
 
+  // theme and its config
+  theme: '@vuepress/theme-default',
   themeConfig: {
     logo: 'https://vuejs.org/images/logo.png',
   },
@@ -39,10 +42,13 @@ import { defineUserConfig } from 'vuepress'
 import type { DefaultThemeOptions } from 'vuepress'
 
 export default defineUserConfig<DefaultThemeOptions>({
+  // site config
   lang: 'en-US',
   title: 'Hello VuePress',
   description: 'Just playing around',
 
+  // theme and its config
+  theme: '@vuepress/theme-default',
   themeConfig: {
     logo: 'https://vuejs.org/images/logo.png',
   },
@@ -53,12 +59,12 @@ export default defineUserConfig<DefaultThemeOptions>({
 </CodeGroup>
 
 ::: tip
-We will refer the config object as **VuePress Config**.
+Check out the [Config Reference](../reference/config.md) for a full list of VuePress config.
 :::
 
 ## Config Scopes
 
-You may have noticed that there is a `themeConfig` option in VuePress Config.
+You may have noticed that there is a `themeConfig` option in VuePress config.
 
 Options outside `themeConfig` are **Site Config**, while options inside `themeConfig` are **Theme Config**.
 
@@ -68,15 +74,11 @@ Site config means that, no matter what theme you are using, these configurations
 
 As we know, every site should have its own `lang`, `title`, `description`, etc. Thus, VuePress has built-in support for those options.
 
-::: tip
-Check out the [Config Reference](../reference/config.md) for a full list of site config.
-:::
-
 ### Theme Config
 
 Theme config will be processed by VuePress theme, so it depends on the theme you are using.
 
-If you don't specify the `theme` option of VuePress Config, the default theme will be used.
+If you don't specify the `theme` option of VuePress config, the default theme will be used.
 
 ::: tip
 Check out the [Default Theme > Config Reference](../reference/default-theme/config.md) for theme config of default theme.

docs/guide/theme.md

@@ -41,11 +41,11 @@ First, create the local theme directory, typically `.vuepress/theme` :
    └─ README.md
 ```
 
-Then, set the absolute path of the theme directory to use it:
+Then, set the [theme](../reference/config.md#theme) option to the absolute path of the [theme entry](../advanced/theme.md#theme-entry) to use it:
 
 ```js
 module.exports = {
-  theme: path.resolve(__dirname, './path/to/docs/.vuepress/theme'),
+  theme: path.resolve(__dirname, './path/to/docs/.vuepress/theme/index.js'),
 }
 ```
 

docs/reference/config.md

@@ -168,6 +168,7 @@ module.exports = {
 ```
 
 - Also see:
+  - [themeConfig](#themeconfig)
   - [Guide > Theme](../guide/theme.md)
 
 ### themeConfig
@@ -178,9 +179,23 @@ module.exports = {
 
 - Details:
 
-  Provide config options to the used theme. The options will vary depending on the theme you are using.
+  Provide config to the used theme. The options will vary depending on the theme you are using.
+
+- Example:
+
+```js
+module.exports = {
+  // use default theme
+  theme: '@vuepress/theme-default',
+  // configure default theme
+  themeConfig: {
+    logo: '/logo.png',
+  },
+}
+```
 
 - Also see:
+  - [theme](#theme)
   - [Default Theme > Config](./default-theme/config.md)
 
 ## Bundler Config

docs/zh/guide/configuration.md

@@ -20,10 +20,13 @@ VuePress 站点必要的配置文件是 `.vuepress/config.js`，它应该导出
 
 ```js
 module.exports = {
+  // 站点配置
   lang: 'zh-CN',
   title: '你好， VuePress ！',
   description: '这是我的第一个 VuePress 站点',
 
+  // 主题和它的配置
+  theme: '@vuepress/theme-default',
   themeConfig: {
     logo: 'https://vuejs.org/images/logo.png',
   },
@@ -39,10 +42,13 @@ import { defineUserConfig } from 'vuepress'
 import type { DefaultThemeOptions } from 'vuepress'
 
 export default defineUserConfig<DefaultThemeOptions>({
+  // 站点配置
   lang: 'en-US',
   title: 'Hello VuePress',
   description: 'Just playing around',
 
+  // 主题和它的配置
+  theme: '@vuepress/theme-default',
   themeConfig: {
     logo: 'https://vuejs.org/images/logo.png',
   },
@@ -53,7 +59,7 @@ export default defineUserConfig<DefaultThemeOptions>({
 </CodeGroup>
 
 ::: tip
-我们接下来会把这个配置对象称为 **VuePress 配置**.
+前往 [配置参考](../reference/config.md) 查看所有 VuePress 配置。
 :::
 
 ## 配置作用域
@@ -68,10 +74,6 @@ export default defineUserConfig<DefaultThemeOptions>({
 
 我们知道，每一个站点都应该有它的 `lang`, `title` 和 `description` 等属性，因此 VuePress 内置支持了这些属性的配置。
 
-::: tip
-前往 [配置参考](../reference/config.md) 查看所有站点配置。
-:::
-
 ### 主题配置
 
 主题配置将会被 VuePress 主题来处理，所以它取决于你使用的主题是什么。

docs/zh/guide/theme.md

@@ -41,11 +41,11 @@ module.exports = {
    └─ README.md
 ```
 
-然后，设置主题目录的绝对路径来使用它：
+然后，将 [theme](../reference/config.md#theme) 配置项设置为 [主题入口](../advanced/theme.md#主题入口) 的绝对路径来使用它：
 
 ```js
 module.exports = {
-  theme: path.resolve(__dirname, './path/to/docs/.vuepress/theme'),
+  theme: path.resolve(__dirname, './path/to/docs/.vuepress/theme/index.js'),
 }
 ```
 

docs/zh/reference/config.md

@@ -167,6 +167,7 @@ module.exports = {
 ```
 
 - 参考：
+  - [themeConfig](#themeconfig)
   - [指南 > 主题](../guide/theme.md)
 
 ### themeConfig
@@ -179,7 +180,21 @@ module.exports = {
 
   为当前使用的主题提供的配置项。具体的配置项取决于你使用的主题。
 
+- 示例：
+
+```js
+module.exports = {
+  // 使用默认主题
+  theme: '@vuepress/theme-default',
+  // 配置默认主题
+  themeConfig: {
+    logo: '/logo.png',
+  },
+}
+```
+
 - 参考：
+  - [theme](#theme)
   - [默认主题 > 配置](./default-theme/config.md)
 
 ## 打包工具配置