docs: add theme-api reference

Author: meteorlxy

docs/reference/plugin-api.md

@@ -37,7 +37,7 @@ The following hooks will be processed in dev / build:
 
   It will be used for identifying plugins to avoid using a same plugin multiple times, so make sure to use a unique plugin name.
 
-  It is recommended to use following format:
+  It should follow the naming convention:
 
   - Non-scoped: `vuepress-plugin-foo`
   - Scoped: `@org/vuepress-plugin-foo`

docs/reference/theme-api.md

@@ -1,3 +1,99 @@
 # Theme API
 
-> TODO
+VuePress theme also works as a plugin, so Theme API can accept all the options of [Plugin API](./plugin-api.md) with following differences.
+
+## Basic Options
+
+### name
+
+- Type: `string`
+
+- Details:
+
+  Name of the theme.
+
+  It should follow the naming convention:
+
+  - Non-scoped: `vuepress-theme-foo`
+  - Scoped: `@org/vuepress-theme-foo`
+
+### multiple
+
+- Details:
+
+  A theme should never be used multiple times, so this option should not be set.
+
+## Theme Specific Options
+
+### layouts
+
+- Type: `string | Record<string, string>`
+
+- Details:
+
+  Specify layout components of the theme.
+
+  It accepts absolute path of the layouts directory. All the `.vue,.ts,.js` files in the directory will be registered as layout components.
+
+  It also accepts a plain object, of which the key is the layout name and the value is the absolute path of the layout file.
+
+  A theme must have at least two layouts: `Layout` and `NotFound`.
+
+- Example:
+
+The layout directory:
+
+```bash
+layouts
+├─ Layout.vue
+├─ NotFound.vue
+└─ FooBar.vue
+```
+
+Using the absolute path of layout directory:
+
+```js
+module.exports = {
+  layouts: path.resolve(__dirname, 'path/to/layouts'),
+}
+```
+
+Using a plain object is equivalent:
+
+```js
+module.exports = {
+  layouts: {
+    Layout: path.resolve(__dirname, 'path/to/layouts/Layout.vue'),
+    NotFound: path.resolve(__dirname, 'path/to/layouts/NotFound.vue'),
+    FooBar: path.resolve(__dirname, 'path/to/layouts/FooBar.vue'),
+  },
+}
+```
+
+### extends
+
+- Type: `string`
+
+- Details:
+
+  The name of the theme to inherit.
+
+  All of the Theme API of the parent theme will be inherited, but the child theme will not override the parent theme.
+
+  If a layout with the same name is registered in both the child theme and the parent theme, the layout of the child theme will have a higher priority.
+
+  Multi-level inheritance is not supported.
+
+- Example:
+
+```js
+module.exports = {
+  // inherit the default theme
+  extends: '@vuepress/theme-default',
+
+  // override the `NotFound` layout
+  layouts: {
+    NotFound: path.resolve(__dirname, 'path/to/NotFound.vue'),
+  },
+}
+```

docs/zh/reference/plugin-api.md

@@ -37,7 +37,7 @@
 
   它会被用来识别插件，以避免多次使用同一个插件，因此应确保你的插件名称是独一无二的。
 
-  建议使用以下命名格式：
+  它应遵从如下命名约定：
 
   - 非 Scoped: `vuepress-plugin-foo`
   - Scoped: `@org/vuepress-plugin-foo`

docs/zh/reference/theme-api.md

@@ -1,3 +1,99 @@
 # 主题 API
 
-> TODO
+VuePress 主题同样是一个插件，因此主题 API 可以接收 [插件 API](./plugin-api.md) 的所有选项，但存在以下差别：
+
+## 基础配置项
+
+### name
+
+- 类型： `string`
+
+- 详情：
+
+  主题的名称。
+
+  它应遵从如下命名约定：
+
+  - 非 Scoped: `vuepress-theme-foo`
+  - Scoped: `@org/vuepress-theme-foo`
+
+### multiple
+
+- 详情：
+
+  主题永远不能被多次使用，因此不应设置该配置项。
+
+## 主题特定配置项
+
+### layouts
+
+- 类型： `string | Record<string, string>`
+
+- 详情：
+
+  指定主题的布局组件。
+
+  它可以接收布局目录的绝对路径。该目录下的所有 `.vue,.ts,.js` 文件都会被注册为布局组件。
+
+  它还可以接收一个普通对象，其键是布局名称，值是布局文件的绝对路径。
+
+  一个主题必须至少有两个布局： `Layout` 和 `NotFound` 。
+
+- 示例：
+
+布局目录：
+
+```bash
+layouts
+├─ Layout.vue
+├─ NotFound.vue
+└─ FooBar.vue
+```
+
+使用布局目录的绝对路径：
+
+```js
+module.exports = {
+  layouts: path.resolve(__dirname, 'path/to/layouts'),
+}
+```
+
+使用普通对象是等效的：
+
+```js
+module.exports = {
+  layouts: {
+    Layout: path.resolve(__dirname, 'path/to/layouts/Layout.vue'),
+    NotFound: path.resolve(__dirname, 'path/to/layouts/NotFound.vue'),
+    FooBar: path.resolve(__dirname, 'path/to/layouts/FooBar.vue'),
+  },
+}
+```
+
+### extends
+
+- 类型： `string`
+
+- 详情：
+
+  要继承的主题名称。
+
+  父主题的所有主题 API 都会被继承，但是子主题不会覆盖父主题。
+
+  如果在子主题和父主题中都注册了具有相同名称的布局，则子主题的布局将具有更高的优先级。
+
+  不支持多级继承。
+
+- 示例：
+
+```js
+module.exports = {
+  // 继承默认主题
+  extends: '@vuepress/theme-default',
+
+  // 覆盖 `NotFound` 布局
+  layouts: {
+    NotFound: path.resolve(__dirname, 'path/to/NotFound.vue'),
+  },
+}
+```