|
1 |
| -# Theme Inheritance |
| 1 | +# Theme Inheritance <Badge type="warn" text="beta" /> |
2 | 2 |
|
3 | 3 | ## Motivation
|
4 | 4 |
|
| 5 | +We have two main reasons to support this feature: |
| 6 | + |
| 7 | +1. VuePress provides users with a [default theme](./default-theme-config.md), which meets the needs of document writers in most scenarios, even so, there are still many users who choose to `eject` and modify, even if they may only need to make minor changes to one of the components. |
| 8 | + |
| 9 | +2. In [0.x](https://vuepress.vuejs.org/guide/custom-themes.html#site-and-page-metadata), only one `Layout.vue` is needed for a theme, so we can achieve simple expansion by directly wrapping `Layout.vue` of another theme. |
| 10 | + |
| 11 | + By 1.x, the elements of a theme has become more complex, we have started to have [theme level configuration](./option-api.md), which supports plugins, custom global layout, etc. In addition, we have also introduced the [directory structure conventions](./writing-a-theme.md#directory-structure) on theme development, such as `styles/index.styl`, under this background, we can not achieve inheritance as 0.x did. |
| 12 | + |
| 13 | +Therefore, we need to provide a reasonable and reliable theme inheritance strategy. |
| 14 | + |
| 15 | +## Concepts |
| 16 | + |
| 17 | +To introduce this section, let's start with a few basic concepts: |
| 18 | + |
| 19 | +- **Atomic theme**:i.e. the parent theme, which is implemented entirely from scratch, like the default theme. |
| 20 | +- **Derived theme**:i.e. the child theme, created based on parent theme; |
| 21 | + |
| 22 | +::: tip |
| 23 | +For now theme inheritance doesn't support high-level inheritance, that means, a derived topic cannot be inherited. |
| 24 | +::: |
| 25 | + |
| 26 | +## Usage |
| 27 | + |
| 28 | +Suppose you want to create a theme inherited from the default theme of VuePress, you just need to configure the [extend](./option-api.md#extend) option in your theme configuration: |
| 29 | + |
| 30 | +```js |
| 31 | +module.exports = { |
| 32 | + extend: '@vuepress/theme-default' |
| 33 | +} |
| 34 | +``` |
| 35 | + |
| 36 | +## Inheritance Strategy |
| 37 | + |
| 38 | +**All the capabilities of the parent theme will be `"passed"` to the child theme. For file-level conventions, child theme can override it by creating a file with the same name in the same location. For some theme configuration options, such as [globalLayout](./option-api.md/globallayout), child theme can override it by the same name configuration.** |
| 39 | + |
| 40 | +The [file-level agreement](./writing-a-theme.md#directory-structure) at are as follows: |
| 41 | + |
| 42 | +- **Global Components**,i.e. the Vue components under `theme/global-components`. |
| 43 | +- **Components**,i.e. the Vue components under `theme/components`. |
| 44 | +- **Global Style and Palette**,i.e. `index.styl` and `palette.styl` under `theme/styles`. |
| 45 | +- **HTML Template**,i.e. `dev.html` and `ssr.html` under `theme/templates`. |
| 46 | +- **Theme-Level App Enhancement File**,i.e. `theme/enhanceApp.js` |
| 47 | + |
| 48 | +For theme configuration, the configuration options that can be overrode by child theme are as follows: |
| 49 | + |
| 50 | +- [devTemplate](./option-api.md#devtemplate) |
| 51 | +- [ssrTemplate](./option-api.md#ssrtemplate) |
| 52 | +- [globalLayout](./option-api.md#globallayout) |
| 53 | + |
| 54 | +Theme configuration options that cannot be overrode by child theme: |
| 55 | + |
| 56 | +- [extend](./option-api.md#extend) |
| 57 | + |
| 58 | +Theme configuration options requiring special treatment: |
| 59 | + |
| 60 | +- [plugins](./option-api.md#plugins):See [Override Plugins](#override-plugins)。 |
| 61 | + |
| 62 | +## Override Plugins |
| 63 | + |
| 64 | +For [plugins](./option-api.md#plugins) in the parent theme, the child theme cannot override it intuitively, but the options of plugin can be overrode by creating plugin configuration with the same name. |
| 65 | + |
| 66 | +For example, if the parent theme has the following configuration: |
| 67 | + |
| 68 | +```js |
| 69 | +// parentThemePath/index.js |
| 70 | +module.exports = { |
| 71 | + plugins: [ |
| 72 | + ['@vuepress/search', { |
| 73 | + searchMaxSuggestions: 5 |
| 74 | + }] |
| 75 | + ] |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +The child theme can modify the options of plugin in the following ways: |
| 80 | + |
| 81 | +```js |
| 82 | +// themePath/index.js |
| 83 | +module.exports = { |
| 84 | + plugins: [ |
| 85 | + ['@vuepress/search', { |
| 86 | + searchMaxSuggestions: 10 |
| 87 | + }] |
| 88 | + ] |
| 89 | +} |
| 90 | +``` |
| 91 | + |
| 92 | +Child theme can even disable it: |
| 93 | + |
| 94 | +```js |
| 95 | +// themePath/index.js |
| 96 | +module.exports = { |
| 97 | + plugins: [ |
| 98 | + ['@vuepress/search', false] |
| 99 | + ] |
| 100 | +} |
| 101 | +``` |
| 102 | + |
| 103 | +::: warning |
| 104 | +Normally, you don't need to do this unless you know clearly that disabling plugins in parent themes won't cause problems. |
| 105 | +::: |
| 106 | + |
| 107 | +## Override Components |
| 108 | + |
| 109 | +You may want to override the same-name components in the parent theme. By default, when the components in the parent theme use relative paths to reference other components, you will not be able to do this because you cannot modify the code of the parent theme at run time. |
| 110 | + |
| 111 | +VuePress achieves this requirement in a clever way, but there is a requirement for the parent theme - **All components must use the `@theme` alias to refer to other components**. |
| 112 | + |
| 113 | +For example, if you are developing an atomic theme with the following structure: |
| 114 | + |
| 115 | +::: vue |
| 116 | +theme |
| 117 | +├── components |
| 118 | +│ ├── `Home.vue` |
| 119 | +│ ├── `Navbar.vue` |
| 120 | +│ └── `Sidebar.vue` |
| 121 | +├── layouts |
| 122 | +│ ├── `404.vue` |
| 123 | +│ └── `Layout.vue` |
| 124 | +├── package.json |
| 125 | +└── index.js |
| 126 | +::: |
| 127 | + |
| 128 | +Then, in any Vue components on the theme, **you should access the theme root directory through `@theme`**: |
| 129 | + |
| 130 | +```vue |
| 131 | +<script> |
| 132 | +import Home from '@theme/components/Navbar.vue' |
| 133 | +// ... |
| 134 | +</script> |
| 135 | +``` |
| 136 | + |
| 137 | +On this premise, when you create a `Navbar` component in the same place in the child theme |
| 138 | + |
| 139 | +::: vue |
| 140 | +theme |
| 141 | +└── components |
| 142 | + └── `Navbar.vue` |
| 143 | +::: |
| 144 | + |
| 145 | +`@theme/components/Navbar.vue` will automatically map to the Navbar component in the child theme. and when you remove the component, `@theme/components/Navbar.vue` will automatically restore to the Navbar component in the parent theme. |
| 146 | + |
| 147 | +In this way, you can easily "tamper" with some part of an atomic theme. |
| 148 | + |
| 149 | +::: tip |
| 150 | +1. You'd better override the component based on the code of the corresponding component in the parent theme. |
| 151 | +2. Currently, when developing theme locally, you need to manually restart dev serverwhen a component is created or removed. |
| 152 | +::: |
| 153 | + |
| 154 | +## Access Parent Theme |
| 155 | + |
| 156 | +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 simply 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 based on the default theme. |
| 157 | + |
| 158 | +```vue |
| 159 | +<!-- themePath/components/Foo.vue --> |
| 160 | +<template> |
| 161 | + <ParentLayout> |
| 162 | + <Foo slot="foo"/> |
| 163 | + </ParentLayout> |
| 164 | +</template> |
| 165 | +
|
| 166 | +<script> |
| 167 | +import ParentLayout from '@parent-theme/layouts/Layout.vue' |
| 168 | +import Foo from '@theme/components/Foo.vue' |
| 169 | +
|
| 170 | +export default { |
| 171 | + components: { |
| 172 | + ParentLayout, |
| 173 | + Foo |
| 174 | + } |
| 175 | +} |
| 176 | +</script> |
| 177 | +``` |
| 178 | + |
5 | 179 |
|
6 | 180 |
|
7 |
| -## What is Subject Inheritance? |
8 | 181 |
|
9 | 182 |
|
0 commit comments