docs: add extending-a-theme recipe (close #104)

Author: meteorlxy

Diff for: docs/.vuepress/configs/sidebar/en.ts

@@ -38,6 +38,7 @@ export const en: SidebarConfig = {
         '/advanced/cookbook/README.md',
         '/advanced/cookbook/usage-of-client-app-enhance.md',
         '/advanced/cookbook/adding-extra-pages.md',
+        '/advanced/cookbook/extending-a-theme.md',
         '/advanced/cookbook/markdown-and-vue-sfc.md',
       ],
     },

Diff for: docs/.vuepress/configs/sidebar/zh.ts

@@ -38,6 +38,7 @@ export const zh: SidebarConfig = {
         '/zh/advanced/cookbook/README.md',
         '/zh/advanced/cookbook/usage-of-client-app-enhance.md',
         '/zh/advanced/cookbook/adding-extra-pages.md',
+        '/zh/advanced/cookbook/extending-a-theme.md',
         '/zh/advanced/cookbook/markdown-and-vue-sfc.md',
       ],
     },

Diff for: docs/.vuepress/public/images/cookbook/extending-a-theme-01.png

@@ -0,0 +1,79 @@
+# Extending a Theme
+
+Sometimes you might want make some minor changes to a theme, but you may not want to fork and modify the entire project.
+
+With the help of [Theme API](../../reference/theme-api.md), you can extend a theme and make your own modifications:
+
+```js
+module.exports = {
+  // your theme
+  name: 'vuepress-theme-foo',
+  // parent theme to extend
+  extends: 'vuepress-theme-bar',
+  // override layouts of parent theme
+  layouts: {
+    Layout: path.resolve(__dirname, 'layouts/Layout.vue'),
+  },
+}
+```
+
+In this case, your `vuepress-theme-foo` will inherit all configuration, plugins and layouts from `vuepress-theme-bar`, and you can override corresponding layouts as needed.
+
+## Extending Default Theme
+
+First, create the theme directory and theme entry `.vuepress/theme/index.js`:
+
+```js
+const { path } = require('@vuepress/utils')
+
+module.exports = {
+  name: 'vuepress-theme-local',
+  extends: '@vuepress/theme-default',
+  layouts: {
+    Layout: path.resolve(__dirname, 'layouts/Layout.vue'),
+  },
+}
+```
+
+You local theme will extends default theme, and override the `Layout` layout.
+
+Next, create `.vuepress/layouts/Layout.vue`, and make use of the slots that provided by the `Layout` of default theme:
+
+```vue
+<template>
+  <Layout>
+    <template #page-bottom>
+      <div class="my-footer">This is my custom page footer</div>
+    </template>
+  </Layout>
+</template>
+
+<script>
+import Layout from '@vuepress/theme-default/lib/client/layouts/Layout.vue'
+
+export default {
+  components: {
+    Layout,
+  },
+}
+</script>
+
+<style lang="css">
+.my-footer {
+  text-align: center;
+}
+</style>
+```
+
+You will add a custom footer to every normal pages in default theme (excluding homepage):
+
+![extending-a-theme](/images/cookbook/extending-a-theme-01.png)
+
+Here are all the slots that provided by the `Layout` of default theme:
+
+- `navbar-before`
+- `navbar-after`
+- `sidebar-top`
+- `sidebar-bottom`
+- `page-top`
+- `page-bottom`

Diff for: docs/advanced/cookbook/extending-a-theme.md

@@ -0,0 +1,79 @@
+# 继承一个主题
+
+有时你可能希望对一个主题进行一些小改动，但是又不想 Fork 并修改整个项目。
+
+借助于 [主题 API](../../reference/theme-api.md) ，你可以继承一个主题并添加你自己的改动：
+
+```ts
+export default {
+  // 你的主题
+  name: 'vuepress-theme-foo',
+  // 要继承的父主题
+  extends: 'vuepress-theme-bar',
+  // 覆盖父主题的布局
+  layouts: {
+    Layout: path.resolve(__dirname, 'layouts/Layout.vue'),
+  },
+};
+```
+
+在这个例子中，你的 `vuepress-theme-foo` 将会继承 `vuepress-theme-bar` 的全部配置、插件和布局，并且你可以按照需要来覆盖对应的布局。
+
+## 继承默认主题
+
+首先，创建主题目录和主题入口 `.vuepress/theme/index.js` ：
+
+```js
+const { path } = require('@vuepress/utils')
+
+module.exports = {
+  name: 'vuepress-theme-local',
+  extends: '@vuepress/theme-default',
+  layouts: {
+    Layout: path.resolve(__dirname, 'layouts/Layout.vue'),
+  },
+}
+```
+
+你的本地主题将会继承默认主题，并且覆盖 `Layout` 布局。
+
+接下来，创建 `.vuepress/layouts/Layout.vue` ，并使用由默认主题的 `Layout` 提供的插槽：
+
+```vue
+<template>
+  <Layout>
+    <template #page-bottom>
+      <div class="my-footer">This is my custom page footer</div>
+    </template>
+  </Layout>
+</template>
+
+<script>
+import Layout from '@vuepress/theme-default/lib/client/layouts/Layout.vue'
+
+export default {
+  components: {
+    Layout,
+  },
+}
+</script>
+
+<style lang="css">
+.my-footer {
+  text-align: center;
+}
+</style>
+```
+
+你将会在除了首页外的所有页面添加一个自定义的页脚：
+
+![extending-a-theme](/images/cookbook/extending-a-theme-01.png)
+
+下面列出了默认主题的 `Layout` 所提供的所有插槽：
+
+- `navbar-before`
+- `navbar-after`
+- `sidebar-top`
+- `sidebar-bottom`
+- `page-top`
+- `page-bottom`