docs: add making-your-theme-extendable section

Author: meteorlxy

docs/advanced/cookbook/extending-a-theme.md

@@ -77,3 +77,71 @@ Here are all the slots that provided by the `Layout` of default theme:
 - `sidebar-bottom`
 - `page-top`
 - `page-bottom`
+
+## Making Your Theme Extendable
+
+As a theme author, you might want to make your theme extendable, allowing users to use your theme with their own customization.
+
+You can provide slots in your layouts, just like how default theme does. This approach requires you to determine which parts of your theme could be extended. It is more suitable for those common customizations like page footer or header:
+
+```vue
+<template>
+  <div class="my-theme-layout">
+    <slot name="page-header" />
+    <Content />
+    <slot name="page-footer" />
+  </div>
+</template>
+```
+
+If you think it is not flexible enough, you can try some more aggressive approaches to make each components of you theme replaceable.
+
+For example, set `alias` for each components of you theme:
+
+```js
+module.exports = {
+  name: 'vuepress-theme-foo',
+  alias: {
+    // set alias for replaceable components
+    '@theme/Navbar.vue': path.resolve(__dirname, 'components/Navbar.vue'),
+    '@theme/Sidebar.vue': path.resolve(__dirname, 'components/Sidebar.vue'),
+  },
+}
+```
+
+Next, use those components via aliases in your theme:
+
+```vue
+<template>
+  <div class="my-theme-layout">
+    <Navbar />
+    <Sidebar />
+    <Content />
+  </div>
+</template>
+
+<script>
+import Navbar from '@theme/Navbar.vue'
+import Sidebar from '@theme/Sidebar.vue'
+
+export default {
+  components: {
+    Navbar,
+    Sidebar,
+  },
+}
+</script>
+```
+
+Then, users can replace specific components by overriding the `alias` when extending your theme:
+
+```js
+module.exports = {
+  name: 'vuepress-theme-foobar',
+  extends: 'vuepress-theme-foo'
+  alias: {
+    // replace the Navbar component
+    '@theme/Navbar.vue': path.resolve(__dirname, 'components/CustomNavbar.vue'),
+  },
+}
+```

docs/zh/advanced/cookbook/extending-a-theme.md

@@ -77,3 +77,71 @@ export default {
 - `sidebar-bottom`
 - `page-top`
 - `page-bottom`
+
+## 使你的主题可以被继承
+
+作为一个主题作者，为了允许用户在使用你的主题时进行更多的自定义，你可能希望你的主题可以被用户继承。
+
+你可以像默认主题的做法一样，在你的布局中添加插槽。这种方式需要你来决定主题的哪些部分是可以被扩展的，它更适合用于一些常见的自定义需求，比如页眉或页脚：
+
+```vue
+<template>
+  <div class="my-theme-layout">
+    <slot name="page-header" />
+    <Content />
+    <slot name="page-footer" />
+  </div>
+</template>
+```
+
+如果你觉得这种方式还不够灵活，你可以尝试一些更激进的做法，使你主题的每个组件都可以被替换。
+
+比如，为你主题的每个组件都设置 `alias` 别名：
+
+```js
+module.exports = {
+  name: 'vuepress-theme-foo',
+  alias: {
+    // 为可替换的组件设置别名
+    '@theme/Navbar.vue': path.resolve(__dirname, 'components/Navbar.vue'),
+    '@theme/Sidebar.vue': path.resolve(__dirname, 'components/Sidebar.vue'),
+  },
+}
+```
+
+然后，在你的主题中通过别名来使用这些组件：
+
+```vue
+<template>
+  <div class="my-theme-layout">
+    <Navbar />
+    <Sidebar />
+    <Content />
+  </div>
+</template>
+
+<script>
+import Navbar from '@theme/Navbar.vue'
+import Sidebar from '@theme/Sidebar.vue'
+
+export default {
+  components: {
+    Navbar,
+    Sidebar,
+  },
+}
+</script>
+```
+
+这样，用户在继承你的主题时，就可以通过覆盖 `alias` 来替换特定的组件了：
+
+```js
+module.exports = {
+  name: 'vuepress-theme-foobar',
+  extends: 'vuepress-theme-foo'
+  alias: {
+    // 替换 Navbar 组件
+    '@theme/Navbar.vue': path.resolve(__dirname, 'components/CustomNavbar.vue'),
+  },
+}
+```