feat(theme-default): make all non-global components replaceable

Author: meteorlxy

docs/.vuepress/configs/navbar/en.ts

@@ -40,6 +40,7 @@ export const en: NavbarConfig = [
           '/reference/default-theme/components.md',
           '/reference/default-theme/markdown.md',
           '/reference/default-theme/styles.md',
+          '/reference/default-theme/extending.md',
         ],
       },
     ],

docs/.vuepress/configs/navbar/zh.ts

@@ -37,6 +37,7 @@ export const zh: NavbarConfig = [
           '/zh/reference/default-theme/components.md',
           '/zh/reference/default-theme/markdown.md',
           '/zh/reference/default-theme/styles.md',
+          '/zh/reference/default-theme/extending.md',
         ],
       },
     ],

docs/.vuepress/configs/sidebar/en.ts

@@ -35,7 +35,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/making-a-theme-extendable.md',
         '/advanced/cookbook/passing-data-to-client-code.md',
         '/advanced/cookbook/markdown-and-vue-sfc.md',
       ],
@@ -70,6 +70,7 @@ export const en: SidebarConfig = {
         '/reference/default-theme/components.md',
         '/reference/default-theme/markdown.md',
         '/reference/default-theme/styles.md',
+        '/reference/default-theme/extending.md',
       ],
     },
     {

docs/.vuepress/configs/sidebar/zh.ts

@@ -35,7 +35,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/making-a-theme-extendable.md',
         '/zh/advanced/cookbook/passing-data-to-client-code.md',
         '/zh/advanced/cookbook/markdown-and-vue-sfc.md',
       ],
@@ -73,6 +73,7 @@ export const zh: SidebarConfig = {
         '/zh/reference/default-theme/components.md',
         '/zh/reference/default-theme/markdown.md',
         '/zh/reference/default-theme/styles.md',
+        '/zh/reference/default-theme/extending.md',
       ],
     },
     {

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

@@ -0,0 +1,59 @@
+# Making a Theme Extendable
+
+Sometimes users might want make some minor changes to a theme, but they don't want to fork and modify the entire project.
+
+With the help of [Theme API](../../reference/theme-api.md), you can make your theme extendable, allowing users to make their own modifications easily.
+
+You must have known that how to [extend default theme](../../reference/default-theme/extending.md). Here we'll introduce how to make your own theme extendable like default theme.
+
+## Layout Slots
+
+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.
+
+You just need to provide slots in your layouts, and tell users how to make use of them:
+
+```vue
+<template>
+  <div class="my-theme-layout">
+    <slot name="page-header" />
+    <Content />
+    <slot name="page-footer" />
+  </div>
+</template>
+```
+
+## Component Aliases
+
+This approach requires you to consider which components of your theme should be replaceable, and you also need to split components into a suitable granularity.
+
+First, set `alias` for replaceable 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
+<script setup lang="ts">
+import Navbar from '@theme/Navbar.vue'
+import Sidebar from '@theme/Sidebar.vue'
+</script>
+
+<template>
+  <div class="my-theme-layout">
+    <Navbar />
+    <Sidebar />
+    <Content />
+  </div>
+</template>
+```
+
+Then, users can replace specific components by overriding the `alias` when extending or using your theme.

docs/advanced/cookbook/making-a-theme-extendable.md

@@ -221,9 +221,9 @@ Renamed to `extends`.
 
 You can still inherit a parent theme with `extends: 'parent-theme'`, which will extends the plugins, layouts, etc.
 
-The `@theme` and `@parent-theme` aliases are not available now.
+The `@theme` and `@parent-theme` aliases are removed by default, but you can still replace components in default theme with similar approach.
 
-Now multi-level theme inheritance is supported.
+You can refer to [Default Theme > Extending](../reference/default-theme/extending.md) for how to extend default theme.
 
 ### CLI Change