From 8999abab5f15dbebc30257a73d04e129cc0cc583 Mon Sep 17 00:00:00 2001
From: Peter Uithoven <peter@peteruithoven.nl>
Date: Tue, 25 Aug 2020 09:17:18 +0200
Subject: [PATCH] docs: clarify theme config files in code blocks (close #2533)
 (#2534)

---
 packages/docs/docs/theme/default-theme-config.md    | 8 ++++++++
 packages/docs/docs/theme/inheritance.md             | 7 ++++---
 packages/docs/docs/theme/option-api.md              | 7 +++++--
 packages/docs/docs/theme/using-a-theme.md           | 5 +++++
 packages/docs/docs/theme/writing-a-theme.md         | 1 +
 packages/docs/docs/zh/theme/default-theme-config.md | 9 ++++++++-
 packages/docs/docs/zh/theme/inheritance.md          | 8 ++++----
 packages/docs/docs/zh/theme/option-api.md           | 7 +++++--
 packages/docs/docs/zh/theme/using-a-theme.md        | 5 +++++
 packages/docs/docs/zh/theme/writing-a-theme.md      | 3 ++-
 10 files changed, 47 insertions(+), 13 deletions(-)

diff --git a/packages/docs/docs/theme/default-theme-config.md b/packages/docs/docs/theme/default-theme-config.md
index f868c6cfcb..e64da69a72 100644
--- a/packages/docs/docs/theme/default-theme-config.md
+++ b/packages/docs/docs/theme/default-theme-config.md
@@ -86,6 +86,7 @@ module.exports = {
 These links can also be dropdown menus if you provide an array of `items` instead of a `link`:
 
 ```js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     nav: [
@@ -105,6 +106,7 @@ module.exports = {
 You can also have sub groups inside a dropdown by having nested items:
 
 ```js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     nav: [
@@ -177,6 +179,7 @@ sidebarDepth: 2
 The sidebar only displays links for headers in the current active page. You can display all header links for every page with `themeConfig.displayAllHeaders: true`:
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     displayAllHeaders: true // Default: false
@@ -189,6 +192,7 @@ module.exports = {
 By default, the nested header links and the hash in the URL are updated as the user scrolls to view the different sections of the page. This behavior can be disabled with the following theme config:
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     activeHeaderLinks: false, // Default: true
@@ -346,6 +350,7 @@ sidebar: false
 You can disable the built-in search box with `themeConfig.search: false`, and customize how many suggestions will be shown with `themeConfig.searchMaxSuggestions`:
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     search: false,
@@ -383,6 +388,7 @@ If you need full text search, you can use [Algolia Search](#algolia-search).
 The `themeConfig.algolia` option allows you to use [Algolia DocSearch](https://community.algolia.com/docsearch/) to replace the simple built-in search. To enable it, you need to provide at least `apiKey` and `indexName`:
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     algolia: {
@@ -404,6 +410,7 @@ For more options, check out [Algolia DocSearch’s documentation](https://github
 You can define a placeholder for the search box by adding the `searchPlaceholder` attribute:
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     searchPlaceholder: 'Search...'
@@ -416,6 +423,7 @@ module.exports = {
 The `themeConfig.lastUpdated` option allows you to get the UNIX timestamp(ms) of each file’s last `git` commit, and it will also display at the bottom of each page in an appropriate format:
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     lastUpdated: 'Last Updated', // string | boolean
diff --git a/packages/docs/docs/theme/inheritance.md b/packages/docs/docs/theme/inheritance.md
index ca095341da..f18778437d 100644
--- a/packages/docs/docs/theme/inheritance.md
+++ b/packages/docs/docs/theme/inheritance.md
@@ -28,6 +28,7 @@ For now theme inheritance doesn’t support high-order inheritance, that means,
 Suppose you want to create a theme inherited from the default theme, you only need to configure the [extend](./option-api.md#extend) option in your theme configuration:
 
 ```js
+// .vuepress/theme/index.js
 module.exports = {
   extend: '@vuepress/theme-default'
 }
@@ -79,7 +80,7 @@ module.exports = {
 The child theme can edit the options of plugin in the following ways:
 
 ```js
-// themePath/index.js
+// .vuepress/theme/index.js
 module.exports = {
   plugins: [
     ['@vuepress/search', {
@@ -92,7 +93,7 @@ module.exports = {
 Child theme can even disable it:
 
 ```js
-// themePath/index.js
+// .vuepress/theme/index.js
 module.exports = {
   plugins: [
     ['@vuepress/search', false]
@@ -160,7 +161,7 @@ This way, you can "tamper" with some part of an atomic theme.
 You can use `@parent-theme` to access the root path of the parent theme. The following example shows creating a layout component with the same name in a child theme and using slots in the parent theme. [@vuepress/theme-vue](https://github.com/vuejs/vuepress/tree/master/packages/%40vuepress/theme-vue) is created in this way.
 
 ```vue
-<!-- themePath/components/Foo.vue -->
+<!-- .vuepress/theme/components/Foo.vue -->
 <template>
   <ParentLayout>
     <Foo #foo/>
diff --git a/packages/docs/docs/theme/option-api.md b/packages/docs/docs/theme/option-api.md
index c21ef15e54..35d3b2f4cb 100644
--- a/packages/docs/docs/theme/option-api.md
+++ b/packages/docs/docs/theme/option-api.md
@@ -7,6 +7,7 @@ metaTitle: Configuration | Theme
 As with plugins, the theme configuration file `themeEntry` should export a `plain JavaScript object`(`#1`). If the plugin needs to take options, it can be a function that exports a plain object(`#2`). The function will be called with the `siteConfig.themeConfig` as the first argument, along with [ctx](../plugin/context-api.md) which provides some compile-time metadata.
 
 ``` js
+// .vuepress/theme/index.js
 // #1
 module.exports = {
    // ...
@@ -14,6 +15,7 @@ module.exports = {
 ```
 
 ``` js
+// .vuepress/theme/index.js
 // #2
 module.exports = (themeConfig, ctx) => {
    return {
@@ -68,6 +70,7 @@ HTML template path used in `build` mode, default template see [here](https://git
 - Default: undefined
 
 ```js
+// .vuepress/theme/index.js
 module.exports = {
   extend: '@vuepress/theme-default'
 }
@@ -86,7 +89,7 @@ VuePress provides the ability to inherit one theme from another. VuePress will f
 - Default: undefined
 
 ```js
-// themePath/index.js
+// .vuepress/theme/index.js
 module.exports = {
   globalLayout: '/path/to/your/global/vue/sfc'
 }
@@ -97,7 +100,7 @@ Global layout component is a component responsible for the global layout strateg
 For example, when you want to set a global header and footer for your theme, you can do this:
 
 ```vue
-<!-- themePath/layouts/GlobalLayout.vue -->
+<!-- .vuepress/theme/layouts/GlobalLayout.vue -->
 <template>
   <div id="global-layout">
     <header><h1>Header</h1></header>
diff --git a/packages/docs/docs/theme/using-a-theme.md b/packages/docs/docs/theme/using-a-theme.md
index 7cc37b78da..6a527cb366 100644
--- a/packages/docs/docs/theme/using-a-theme.md
+++ b/packages/docs/docs/theme/using-a-theme.md
@@ -7,6 +7,7 @@ Using a theme is almost the same as using a plugin.
 Themes can be published on npm in raw Vue SFC format as `vuepress-theme-xxx`.
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   theme: 'vuepress-theme-xx'
 }
@@ -17,6 +18,7 @@ module.exports = {
 If you prefix the theme with `vuepress-theme-`, you can use a shorthand to leave out that prefix:
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   theme: 'xxx'
 }
@@ -25,6 +27,7 @@ module.exports = {
 Same with:
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   theme: 'vuepress-theme-xxx'
 }
@@ -33,6 +36,7 @@ module.exports = {
 This also works with [Scoped Packages](https://docs.npmjs.com/misc/scope):
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   theme: '@org/vuepress-theme-xxx', // or an official theme: '@vuepress/theme-xxx'
 }
@@ -41,6 +45,7 @@ module.exports = {
 Shorthand:
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   theme: '@org/xxx', // or an official theme: '@vuepress/xxx'
 }
diff --git a/packages/docs/docs/theme/writing-a-theme.md b/packages/docs/docs/theme/writing-a-theme.md
index dab46adc5f..23b29191ee 100644
--- a/packages/docs/docs/theme/writing-a-theme.md
+++ b/packages/docs/docs/theme/writing-a-theme.md
@@ -104,6 +104,7 @@ Each layout component may render distinct pages. To apply some global UI (for ex
 You can apply some plugins to the theme via `theme/index.js`.
 
 ```js
+// .vuepress/theme/index.js
 module.exports = {
   plugins: [
     ['@vuepress/pwa', {
diff --git a/packages/docs/docs/zh/theme/default-theme-config.md b/packages/docs/docs/zh/theme/default-theme-config.md
index f230b88f9a..7d3a442b56 100644
--- a/packages/docs/docs/zh/theme/default-theme-config.md
+++ b/packages/docs/docs/zh/theme/default-theme-config.md
@@ -83,6 +83,7 @@ module.exports = {
 当你提供了一个 `items` 数组而不是一个单一的 `link` 时，它将显示为一个 `下拉列表` ：
 
 ```js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     nav: [
@@ -102,6 +103,7 @@ module.exports = {
 此外，你还可以通过嵌套的 `items` 来在 `下拉列表` 中设置分组：
 
 ```js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     nav: [
@@ -174,6 +176,7 @@ sidebarDepth: 2
 默认情况下，侧边栏只会显示由当前活动页面的标题（headers）组成的链接，你可以将 `themeConfig.displayAllHeaders` 设置为 `true` 来显示所有页面的标题链接：
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     displayAllHeaders: true // 默认值：false
@@ -186,6 +189,7 @@ module.exports = {
 默认情况下，当用户通过滚动查看页面的不同部分时，嵌套的标题链接和 URL 中的 Hash 值会实时更新，这个行为可以通过以下的配置来禁用：
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     activeHeaderLinks: false, // 默认值：true
@@ -338,6 +342,7 @@ sidebar: false
 你可以通过设置 `themeConfig.search: false` 来禁用默认的搜索框，或是通过 `themeConfig.searchMaxSuggestions` 来调整默认搜索框显示的搜索结果数量：
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     search: false,
@@ -350,7 +355,7 @@ module.exports = {
 
 ```yaml
 ---
-tags: 
+tags:
   - 配置
   - 主题
   - 索引
@@ -375,6 +380,7 @@ search: false
 你可以通过 `themeConfig.algolia` 选项来用 [Algolia 搜索](https://community.algolia.com/docsearch/) 替换内置的搜索框。要启用 Algolia 搜索，你需要至少提供 `apiKey` 和 `indexName`：
 
 ```js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     algolia: {
@@ -396,6 +402,7 @@ module.exports = {
 你可以通过 `themeConfig.lastUpdated` 选项来获取每个文件最后一次 `git` 提交的 UNIX 时间戳(ms)，同时它将以合适的日期格式显示在每一页的底部：
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   themeConfig: {
     lastUpdated: 'Last Updated', // string | boolean
diff --git a/packages/docs/docs/zh/theme/inheritance.md b/packages/docs/docs/zh/theme/inheritance.md
index 7e796bf557..55b8d8917e 100644
--- a/packages/docs/docs/zh/theme/inheritance.md
+++ b/packages/docs/docs/zh/theme/inheritance.md
@@ -27,7 +27,7 @@
 假设你想创建一个继承自 VuePress 默认主题的派生主题，你只需要在你的主题配置中配置 [extend](./option-api.md#extend) 选项：
 
 ```js
-// themePath/index.js
+// .vuepress/theme/index.js
 module.exports = {
   extend: '@vuepress/theme-default'
 }
@@ -79,7 +79,7 @@ module.exports = {
 那么子主题可以通过如下方式来修改该插件的默认值：
 
 ```js
-// themePath/index.js
+// .vuepress/theme/index.js
 module.exports = {
   plugins: [
     ['@vuepress/search', {
@@ -92,7 +92,7 @@ module.exports = {
 也可以选择禁用它：
 
 ```js
-// themePath/index.js
+// .vuepress/theme/index.js
 module.exports = {
   plugins: [
     ['@vuepress/search', false]
@@ -156,7 +156,7 @@ theme
 你可以使用 `@parent-theme` 来访问父主题的根路径，下述示例展示了在子主题中创建一个同名的布局组件，并简单使用父主题中的 slot，[@vuepress/theme-vue](https://github.com/vuejs/vuepress/tree/master/packages/%40vuepress/theme-vue) 便是通过这种方式创造的。
 
 ```vue
-<!-- themePath/components/Foo.vue -->
+<!-- .vuepress/theme/components/Foo.vue -->
 <template>
   <ParentLayout>
     <Foo #foo/>
diff --git a/packages/docs/docs/zh/theme/option-api.md b/packages/docs/docs/zh/theme/option-api.md
index 2bfa638051..ef48e2cea8 100644
--- a/packages/docs/docs/zh/theme/option-api.md
+++ b/packages/docs/docs/zh/theme/option-api.md
@@ -7,6 +7,7 @@ metaTitle: Configuration | Theme
 和插件几乎一样，主题的配置文件 `themeEntry` 应该导出一个普通的 JavaScript 对象（`#1`），它也可以是一个返回对象的函数（`#2`），这个函数接受用户在 `siteConfig.themeConfig` 为第一个参数、包含编译期上下文的 [ctx](../plugin/context-api.md) 对象作为第二个参数。
 
 ``` js
+// .vuepress/theme/index.js
 // #1
 module.exports = {
    // ...
@@ -14,6 +15,7 @@ module.exports = {
 ```
 
 ``` js
+// .vuepress/theme/index.js
 // #2
 module.exports = (themeConfig, ctx) => {
    return {
@@ -67,6 +69,7 @@ build 模式下使用的 HTML 模板路径，默认模板见 [这里](https://gi
 - 默认值: undefined
 
 ```js
+// .vuepress/theme/index.js
 module.exports = {
   extend: '@vuepress/theme-default'
 }
@@ -85,7 +88,7 @@ VuePress 支持一个主题继承于另一个主题。VuePress 将遵循 `overri
 - 默认值: undefined
 
 ```js
-// themePath/index.js
+// .vuepress/theme/index.js
 module.exports = {
   globalLayout: '/path/to/your/global/vue/sfc'
 }
@@ -97,7 +100,7 @@ module.exports = {
 
 
 ```vue
-<!-- themePath/layouts/GlobalLayout.vue -->
+<!-- .vuepress/theme/layouts/GlobalLayout.vue -->
 <template>
   <div id="global-layout">
     <header><h1>Header</h1></header>
diff --git a/packages/docs/docs/zh/theme/using-a-theme.md b/packages/docs/docs/zh/theme/using-a-theme.md
index e6b7f3c517..054f0f8e7c 100644
--- a/packages/docs/docs/zh/theme/using-a-theme.md
+++ b/packages/docs/docs/zh/theme/using-a-theme.md
@@ -7,6 +7,7 @@
 一个主题可以在以 `vuepress-theme-xxx` 的形式发布到 npm，你可以这样使用它：
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   theme: 'vuepress-theme-xx'
 }
@@ -17,6 +18,7 @@ module.exports = {
 如果你的主题名以 `vuepress-theme-` 开头，你可以使用缩写来省略这个前缀：
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   theme: 'xxx'
 }
@@ -25,6 +27,7 @@ module.exports = {
 和下面等价：
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   theme: 'vuepress-theme-xxx'
 }
@@ -33,6 +36,7 @@ module.exports = {
 这也适用于 [Scoped Packages](https://docs.npmjs.com/misc/scope):
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   theme: '@org/vuepress-theme-xxx', // 或者一个官方主题: '@vuepress/theme-xxx'
 }
@@ -41,6 +45,7 @@ module.exports = {
 缩写:
 
 ``` js
+// .vuepress/config.js
 module.exports = {
   theme: '@org/xxx', // 或者一个官方主题: '@vuepress/xxx'
 }
diff --git a/packages/docs/docs/zh/theme/writing-a-theme.md b/packages/docs/docs/zh/theme/writing-a-theme.md
index a40b42d907..01c7852382 100644
--- a/packages/docs/docs/zh/theme/writing-a-theme.md
+++ b/packages/docs/docs/zh/theme/writing-a-theme.md
@@ -109,10 +109,11 @@ layout: AnotherLayout
 你可以通过主题的配置文件 `themePath/index.js` 来给主题应用一些插件：
 
 ```js
+// .vuepress/theme/index.js
 module.exports = {
   plugins: [
     '@vuepress/pwa',
-    { 
+    {
       serviceWorker: true,
       updatePopup: true
     }