Skip to content

Commit 8999aba

Browse files
peteruithovenpeteruithoven
authored
docs: clarify theme config files in code blocks (close #2533) (#2534)
1 parent e8afd1e commit 8999aba

10 files changed

+47
-13
lines changed

‎packages/docs/docs/theme/default-theme-config.md

+8
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@ module.exports = {
8686
These links can also be dropdown menus if you provide an array of `items` instead of a `link`:
8787

8888
```js
89+
// .vuepress/config.js
8990
module.exports = {
9091
themeConfig: {
9192
nav: [
@@ -105,6 +106,7 @@ module.exports = {
105106
You can also have sub groups inside a dropdown by having nested items:
106107

107108
```js
109+
// .vuepress/config.js
108110
module.exports = {
109111
themeConfig: {
110112
nav: [
@@ -177,6 +179,7 @@ sidebarDepth: 2
177179
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`:
178180

179181
``` js
182+
// .vuepress/config.js
180183
module.exports = {
181184
themeConfig: {
182185
displayAllHeaders: true // Default: false
@@ -189,6 +192,7 @@ module.exports = {
189192
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:
190193

191194
``` js
195+
// .vuepress/config.js
192196
module.exports = {
193197
themeConfig: {
194198
activeHeaderLinks: false, // Default: true
@@ -346,6 +350,7 @@ sidebar: false
346350
You can disable the built-in search box with `themeConfig.search: false`, and customize how many suggestions will be shown with `themeConfig.searchMaxSuggestions`:
347351

348352
``` js
353+
// .vuepress/config.js
349354
module.exports = {
350355
themeConfig: {
351356
search: false,
@@ -383,6 +388,7 @@ If you need full text search, you can use [Algolia Search](#algolia-search).
383388
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`:
384389

385390
``` js
391+
// .vuepress/config.js
386392
module.exports = {
387393
themeConfig: {
388394
algolia: {
@@ -404,6 +410,7 @@ For more options, check out [Algolia DocSearch’s documentation](https://github
404410
You can define a placeholder for the search box by adding the `searchPlaceholder` attribute:
405411

406412
``` js
413+
// .vuepress/config.js
407414
module.exports = {
408415
themeConfig: {
409416
searchPlaceholder: 'Search...'
@@ -416,6 +423,7 @@ module.exports = {
416423
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:
417424

418425
``` js
426+
// .vuepress/config.js
419427
module.exports = {
420428
themeConfig: {
421429
lastUpdated: 'Last Updated', // string | boolean

‎packages/docs/docs/theme/inheritance.md

+4-3
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ For now theme inheritance doesn’t support high-order inheritance, that means,
2828
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:
2929

3030
```js
31+
// .vuepress/theme/index.js
3132
module.exports = {
3233
extend: '@vuepress/theme-default'
3334
}
@@ -79,7 +80,7 @@ module.exports = {
7980
The child theme can edit the options of plugin in the following ways:
8081

8182
```js
82-
// themePath/index.js
83+
// .vuepress/theme/index.js
8384
module.exports = {
8485
plugins: [
8586
['@vuepress/search', {
@@ -92,7 +93,7 @@ module.exports = {
9293
Child theme can even disable it:
9394

9495
```js
95-
// themePath/index.js
96+
// .vuepress/theme/index.js
9697
module.exports = {
9798
plugins: [
9899
['@vuepress/search', false]
@@ -160,7 +161,7 @@ This way, you can "tamper" with some part of an atomic theme.
160161
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.
161162

162163
```vue
163-
<!-- themePath/components/Foo.vue -->
164+
<!-- .vuepress/theme/components/Foo.vue -->
164165
<template>
165166
<ParentLayout>
166167
<Foo #foo/>

‎packages/docs/docs/theme/option-api.md

+5-2
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,15 @@ metaTitle: Configuration | Theme
77
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.
88

99
``` js
10+
// .vuepress/theme/index.js
1011
// #1
1112
module.exports = {
1213
// ...
1314
}
1415
```
1516

1617
``` js
18+
// .vuepress/theme/index.js
1719
// #2
1820
module.exports = (themeConfig, ctx) => {
1921
return {
@@ -68,6 +70,7 @@ HTML template path used in `build` mode, default template see [here](https://git
6870
- Default: undefined
6971

7072
```js
73+
// .vuepress/theme/index.js
7174
module.exports = {
7275
extend: '@vuepress/theme-default'
7376
}
@@ -86,7 +89,7 @@ VuePress provides the ability to inherit one theme from another. VuePress will f
8689
- Default: undefined
8790

8891
```js
89-
// themePath/index.js
92+
// .vuepress/theme/index.js
9093
module.exports = {
9194
globalLayout: '/path/to/your/global/vue/sfc'
9295
}
@@ -97,7 +100,7 @@ Global layout component is a component responsible for the global layout strateg
97100
For example, when you want to set a global header and footer for your theme, you can do this:
98101

99102
```vue
100-
<!-- themePath/layouts/GlobalLayout.vue -->
103+
<!-- .vuepress/theme/layouts/GlobalLayout.vue -->
101104
<template>
102105
<div id="global-layout">
103106
<header><h1>Header</h1></header>

‎packages/docs/docs/theme/using-a-theme.md

+5
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Using a theme is almost the same as using a plugin.
77
Themes can be published on npm in raw Vue SFC format as `vuepress-theme-xxx`.
88

99
``` js
10+
// .vuepress/config.js
1011
module.exports = {
1112
theme: 'vuepress-theme-xx'
1213
}
@@ -17,6 +18,7 @@ module.exports = {
1718
If you prefix the theme with `vuepress-theme-`, you can use a shorthand to leave out that prefix:
1819

1920
``` js
21+
// .vuepress/config.js
2022
module.exports = {
2123
theme: 'xxx'
2224
}
@@ -25,6 +27,7 @@ module.exports = {
2527
Same with:
2628

2729
``` js
30+
// .vuepress/config.js
2831
module.exports = {
2932
theme: 'vuepress-theme-xxx'
3033
}
@@ -33,6 +36,7 @@ module.exports = {
3336
This also works with [Scoped Packages](https://docs.npmjs.com/misc/scope):
3437

3538
``` js
39+
// .vuepress/config.js
3640
module.exports = {
3741
theme: '@org/vuepress-theme-xxx', // or an official theme: '@vuepress/theme-xxx'
3842
}
@@ -41,6 +45,7 @@ module.exports = {
4145
Shorthand:
4246

4347
``` js
48+
// .vuepress/config.js
4449
module.exports = {
4550
theme: '@org/xxx', // or an official theme: '@vuepress/xxx'
4651
}

‎packages/docs/docs/theme/writing-a-theme.md

+1
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,7 @@ Each layout component may render distinct pages. To apply some global UI (for ex
104104
You can apply some plugins to the theme via `theme/index.js`.
105105

106106
```js
107+
// .vuepress/theme/index.js
107108
module.exports = {
108109
plugins: [
109110
['@vuepress/pwa', {

‎packages/docs/docs/zh/theme/default-theme-config.md

+8-1
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ module.exports = {
8383
当你提供了一个 `items` 数组而不是一个单一的 `link` 时，它将显示为一个 `下拉列表` ：
8484

8585
```js
86+
// .vuepress/config.js
8687
module.exports = {
8788
themeConfig: {
8889
nav: [
@@ -102,6 +103,7 @@ module.exports = {
102103
此外，你还可以通过嵌套的 `items` 来在 `下拉列表` 中设置分组：
103104

104105
```js
106+
// .vuepress/config.js
105107
module.exports = {
106108
themeConfig: {
107109
nav: [
@@ -174,6 +176,7 @@ sidebarDepth: 2
174176
默认情况下，侧边栏只会显示由当前活动页面的标题（headers）组成的链接，你可以将 `themeConfig.displayAllHeaders` 设置为 `true` 来显示所有页面的标题链接：
175177

176178
``` js
179+
// .vuepress/config.js
177180
module.exports = {
178181
themeConfig: {
179182
displayAllHeaders: true // 默认值：false
@@ -186,6 +189,7 @@ module.exports = {
186189
默认情况下，当用户通过滚动查看页面的不同部分时，嵌套的标题链接和 URL 中的 Hash 值会实时更新，这个行为可以通过以下的配置来禁用：
187190

188191
``` js
192+
// .vuepress/config.js
189193
module.exports = {
190194
themeConfig: {
191195
activeHeaderLinks: false, // 默认值：true
@@ -338,6 +342,7 @@ sidebar: false
338342
你可以通过设置 `themeConfig.search: false` 来禁用默认的搜索框，或是通过 `themeConfig.searchMaxSuggestions` 来调整默认搜索框显示的搜索结果数量：
339343

340344
``` js
345+
// .vuepress/config.js
341346
module.exports = {
342347
themeConfig: {
343348
search: false,
@@ -350,7 +355,7 @@ module.exports = {
350355

351356
```yaml
352357
---
353-
tags:
358+
tags:
354359
- 配置
355360
- 主题
356361
- 索引
@@ -375,6 +380,7 @@ search: false
375380
你可以通过 `themeConfig.algolia` 选项来用 [Algolia 搜索](https://community.algolia.com/docsearch/) 替换内置的搜索框。要启用 Algolia 搜索，你需要至少提供 `apiKey` 和 `indexName`：
376381

377382
```js
383+
// .vuepress/config.js
378384
module.exports = {
379385
themeConfig: {
380386
algolia: {
@@ -396,6 +402,7 @@ module.exports = {
396402
你可以通过 `themeConfig.lastUpdated` 选项来获取每个文件最后一次 `git` 提交的 UNIX 时间戳(ms)，同时它将以合适的日期格式显示在每一页的底部：
397403

398404
``` js
405+
// .vuepress/config.js
399406
module.exports = {
400407
themeConfig: {
401408
lastUpdated: 'Last Updated', // string | boolean

‎packages/docs/docs/zh/theme/inheritance.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
假设你想创建一个继承自 VuePress 默认主题的派生主题，你只需要在你的主题配置中配置 [extend](./option-api.md#extend) 选项：
2828

2929
```js
30-
// themePath/index.js
30+
// .vuepress/theme/index.js
3131
module.exports = {
3232
extend: '@vuepress/theme-default'
3333
}
@@ -79,7 +79,7 @@ module.exports = {
7979
那么子主题可以通过如下方式来修改该插件的默认值：
8080

8181
```js
82-
// themePath/index.js
82+
// .vuepress/theme/index.js
8383
module.exports = {
8484
plugins: [
8585
['@vuepress/search', {
@@ -92,7 +92,7 @@ module.exports = {
9292
也可以选择禁用它：
9393

9494
```js
95-
// themePath/index.js
95+
// .vuepress/theme/index.js
9696
module.exports = {
9797
plugins: [
9898
['@vuepress/search', false]
@@ -156,7 +156,7 @@ theme
156156
你可以使用 `@parent-theme` 来访问父主题的根路径，下述示例展示了在子主题中创建一个同名的布局组件，并简单使用父主题中的 slot，[@vuepress/theme-vue](https://github.com/vuejs/vuepress/tree/master/packages/%40vuepress/theme-vue) 便是通过这种方式创造的。
157157

158158
```vue
159-
<!-- themePath/components/Foo.vue -->
159+
<!-- .vuepress/theme/components/Foo.vue -->
160160
<template>
161161
<ParentLayout>
162162
<Foo #foo/>

‎packages/docs/docs/zh/theme/option-api.md

+5-2
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,15 @@ metaTitle: Configuration | Theme
77
和插件几乎一样，主题的配置文件 `themeEntry` 应该导出一个普通的 JavaScript 对象（`#1`），它也可以是一个返回对象的函数（`#2`），这个函数接受用户在 `siteConfig.themeConfig` 为第一个参数、包含编译期上下文的 [ctx](../plugin/context-api.md) 对象作为第二个参数。
88

99
``` js
10+
// .vuepress/theme/index.js
1011
// #1
1112
module.exports = {
1213
// ...
1314
}
1415
```
1516

1617
``` js
18+
// .vuepress/theme/index.js
1719
// #2
1820
module.exports = (themeConfig, ctx) => {
1921
return {
@@ -67,6 +69,7 @@ build 模式下使用的 HTML 模板路径，默认模板见 [这里](https://gi
6769
- 默认值: undefined
6870

6971
```js
72+
// .vuepress/theme/index.js
7073
module.exports = {
7174
extend: '@vuepress/theme-default'
7275
}
@@ -85,7 +88,7 @@ VuePress 支持一个主题继承于另一个主题。VuePress 将遵循 `overri
8588
- 默认值: undefined
8689

8790
```js
88-
// themePath/index.js
91+
// .vuepress/theme/index.js
8992
module.exports = {
9093
globalLayout: '/path/to/your/global/vue/sfc'
9194
}
@@ -97,7 +100,7 @@ module.exports = {
97100

98101

99102
```vue
100-
<!-- themePath/layouts/GlobalLayout.vue -->
103+
<!-- .vuepress/theme/layouts/GlobalLayout.vue -->
101104
<template>
102105
<div id="global-layout">
103106
<header><h1>Header</h1></header>

‎packages/docs/docs/zh/theme/using-a-theme.md

+5
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
一个主题可以在以 `vuepress-theme-xxx` 的形式发布到 npm，你可以这样使用它：
88

99
``` js
10+
// .vuepress/config.js
1011
module.exports = {
1112
theme: 'vuepress-theme-xx'
1213
}
@@ -17,6 +18,7 @@ module.exports = {
1718
如果你的主题名以 `vuepress-theme-` 开头，你可以使用缩写来省略这个前缀：
1819

1920
``` js
21+
// .vuepress/config.js
2022
module.exports = {
2123
theme: 'xxx'
2224
}
@@ -25,6 +27,7 @@ module.exports = {
2527
和下面等价：
2628

2729
``` js
30+
// .vuepress/config.js
2831
module.exports = {
2932
theme: 'vuepress-theme-xxx'
3033
}
@@ -33,6 +36,7 @@ module.exports = {
3336
这也适用于 [Scoped Packages](https://docs.npmjs.com/misc/scope):
3437

3538
``` js
39+
// .vuepress/config.js
3640
module.exports = {
3741
theme: '@org/vuepress-theme-xxx', // 或者一个官方主题: '@vuepress/theme-xxx'
3842
}
@@ -41,6 +45,7 @@ module.exports = {
4145
缩写:
4246

4347
``` js
48+
// .vuepress/config.js
4449
module.exports = {
4550
theme: '@org/xxx', // 或者一个官方主题: '@vuepress/xxx'
4651
}

‎packages/docs/docs/zh/theme/writing-a-theme.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -109,10 +109,11 @@ layout: AnotherLayout
109109
你可以通过主题的配置文件 `themePath/index.js` 来给主题应用一些插件：
110110

111111
```js
112+
// .vuepress/theme/index.js
112113
module.exports = {
113114
plugins: [
114115
'@vuepress/pwa',
115-
{
116+
{
116117
serviceWorker: true,
117118
updatePopup: true
118119
}

0 commit comments

Comments
 (0)