docs: add guide for writing a theme

Author: meteorlxy

docs/guide/advanced/plugin.md

@@ -92,6 +92,6 @@ The [package.json](https://docs.npmjs.com/cli/v6/configuring-npm/package-json) f
 ```
 
 - Set `name` to follow the naming convention: `vuepress-plugin-xxx` or `@org/vuepress-plugin-xxx`.
-- Set `keywords` to include `'vuepress-plugin'`, so that users can search your plugin on NPM.
+- Set `keywords` to include `vuepress-plugin`, so that users can search your plugin on NPM.
 - Set `main` to the plugin entry file.
 - Set `files` to only publish those files inside `lib` directory.

docs/guide/advanced/theme.md

@@ -1,3 +1,130 @@
 # Writing a Theme
 
-> TODO
+::: tip
+Before reading this guide, you'd better learn the guide of [Writing a Plugin](./plugin.md) first.
+:::
+
+A VuePress theme is a special plugin, which should satisfy the [Theme API](../../reference/theme-api.md). Like plugins, a theme can also be a *Theme Object* or a *Theme Function*.
+
+<CodeGroup>
+  <CodeGroupItem title="Theme Object" active>
+
+```js
+const fooTheme = {
+  name: 'vuepress-theme-foo',
+  layouts: {
+    Layout: path.resolve(__dirname, 'layouts/Layout.vue'),
+    404: path.resolve(__dirname, 'layouts/404.vue'),
+  },
+  // ...
+}
+```
+
+  </CodeGroupItem>
+
+  <CodeGroupItem title="Theme Function">
+
+```js
+const fooTheme = (options, app) => {
+  return {
+    name: 'vuepress-theme-foo',
+    layouts: {
+      Layout: path.resolve(__dirname, 'layouts/Layout.vue'),
+      404: path.resolve(__dirname, 'layouts/404.vue'),
+    },
+    // ...
+  }
+}
+```
+
+  </CodeGroupItem>
+</CodeGroup>
+
+## Creating a Theme Package
+
+The typical structure of a theme package is as follow:
+
+```bash
+vuepress-theme-foo
+├─ lib
+│  ├─ layouts
+│  │  ├─ Layout.vue
+│  │  └─ 404.vue
+│  └─ index.js
+└─ package.json
+```
+
+### Theme Entry
+
+The `lib/index.js` file is the theme entry, which should export the theme directly:
+
+<CodeGroup>
+  <CodeGroupItem title="CJS" active>
+
+```js
+module.export = fooTheme
+```
+
+  </CodeGroupItem>
+
+  <CodeGroupItem title="ESM">
+
+```js
+export default fooTheme
+```
+
+  </CodeGroupItem>
+</CodeGroup>
+
+::: tip
+Notice that the theme entry will be loaded in Node, so it should be in CommonJS format.
+
+If you are using ESM format, you'll need to use [babel](https://babeljs.io/) or [typescript](https://www.typescriptlang.org/) to transpile it into CommonJS.
+:::
+
+### package.json
+
+The [package.json](https://docs.npmjs.com/cli/v6/configuring-npm/package-json) file is required to publish a package to NPM:
+
+```json
+{
+  "name": "vuepress-theme-foo",
+  "version": "1.0.0",
+  "keywords": [
+    "vuepress-theme",
+  ],
+  "main": "lib/index.js",
+  "files": [
+    "lib"
+  ]
+}
+```
+
+- Set `name` to follow the naming convention: `vuepress-theme-xxx` or `@org/vuepress-theme-xxx`.
+- Set `keywords` to include `vuepress-theme`, so that users can search your theme on NPM.
+- Set `main` to the theme entry file.
+- Set `files` to only publish those files inside `lib` directory.
+
+### Layouts
+
+A theme must provide at least two layouts: `Layout` and `404`.
+
+The `Layout` layout should contain the [Content](../../reference/components.md#content) component to display the markdown content:
+
+```vue
+<template>
+  <div>
+    <Content />
+  </div>
+</template>
+```
+
+The `404` layout will be used for the `404.html` page:
+
+```vue
+<template>
+  <div>404 Not Found</div>
+</template>
+```
+
+You can provide more layouts, and users can change layout via [layout](../../reference/frontmatter.md#layout) frontmatter.

docs/reference/frontmatter.md

@@ -163,3 +163,5 @@ permalinkPattern: :year/:month/:day/:slug.html
 - Details:
 
   Layout for the page.
+
+  Layouts are provided by theme. If you don't specify this frontmatter, the default layout will be used. A theme may provide other layouts, and you should refer to the theme documentation for detailed guide.

docs/reference/theme-api.md

@@ -37,7 +37,7 @@ VuePress theme also works as a plugin, so Theme API can accept all the options o
 
   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`.
+  A theme must have at least two layouts: `Layout` and `404`.
 
 - Example:
 
@@ -46,7 +46,7 @@ The layout directory:
 ```bash
 layouts
 ├─ Layout.vue
-├─ NotFound.vue
+├─ 404.vue
 └─ FooBar.vue
 ```
 
@@ -64,7 +64,7 @@ Using a plain object is equivalent:
 module.exports = {
   layouts: {
     Layout: path.resolve(__dirname, 'path/to/layouts/Layout.vue'),
-    NotFound: path.resolve(__dirname, 'path/to/layouts/NotFound.vue'),
+    404: path.resolve(__dirname, 'path/to/layouts/404.vue'),
     FooBar: path.resolve(__dirname, 'path/to/layouts/FooBar.vue'),
   },
 }
@@ -91,9 +91,9 @@ module.exports = {
   // inherit the default theme
   extends: '@vuepress/theme-default',
 
-  // override the `NotFound` layout
+  // override the `404` layout
   layouts: {
-    NotFound: path.resolve(__dirname, 'path/to/NotFound.vue'),
+    404: path.resolve(__dirname, 'path/to/404.vue'),
   },
 }
 ```

docs/zh/guide/advanced/plugin.md

@@ -92,6 +92,6 @@ export default fooPlugin
 ```
 
 - 将 `name` 按照约定命名： `vuepress-plugin-xxx` 或 `@org/vuepress-plugin-xxx` 。
-- 在 `keywords` 中包含 `'vuepress-plugin'` ，这样用户可以在 NPM 上搜索到你的插件。
+- 在 `keywords` 中包含 `vuepress-plugin` ，这样用户可以在 NPM 上搜索到你的插件。
 - 将 `main` 设为插件入口文件。
 - 设置 `files` ，仅发布 `lib` 目录下的文件。

docs/zh/guide/advanced/theme.md

@@ -1,3 +1,130 @@
 # 开发主题
 
-> TODO
+::: tip
+在阅读该指南之前，你最好先了解一下 [开发插件](./plugin.md) 指南。
+:::
+
+VuePress 主题是一个特殊的插件，它应该符合 [主题 API](../../reference/theme-api.md) 。和插件一样，主题可以是一个 *主题对象* 或一个 *主题函数* 。
+
+<CodeGroup>
+  <CodeGroupItem title="主题对象" active>
+
+```js
+const fooTheme = {
+  name: 'vuepress-theme-foo',
+  layouts: {
+    Layout: path.resolve(__dirname, 'layouts/Layout.vue'),
+    404: path.resolve(__dirname, 'layouts/404.vue'),
+  },
+  // ...
+}
+```
+
+  </CodeGroupItem>
+
+  <CodeGroupItem title="主题函数">
+
+```js
+const fooTheme = (options, app) => {
+  return {
+    name: 'vuepress-theme-foo',
+    layouts: {
+      Layout: path.resolve(__dirname, 'layouts/Layout.vue'),
+      404: path.resolve(__dirname, 'layouts/404.vue'),
+    },
+    // ...
+  }
+}
+```
+
+  </CodeGroupItem>
+</CodeGroup>
+
+## 创建一个主题 Package
+
+一个典型的主题 Package 的结构如下所示：
+
+```bash
+vuepress-theme-foo
+├─ lib
+│  ├─ layouts
+│  │  ├─ Layout.vue
+│  │  └─ 404.vue
+│  └─ index.js
+└─ package.json
+```
+
+### 主题入口
+
+`lib/index.js` 文件是主题入口，它应当直接导出主题：
+
+<CodeGroup>
+  <CodeGroupItem title="CJS" active>
+
+```js
+module.export = fooTheme
+```
+
+  </CodeGroupItem>
+
+  <CodeGroupItem title="ESM">
+
+```js
+export default fooTheme
+```
+
+  </CodeGroupItem>
+</CodeGroup>
+
+::: tip
+注意，主题入口会在 Node 中被加载，因此它应为 CommonJS 格式。
+
+如果你使用 ESM 格式，你需要使用 [babel](https://babeljs.io/) 或 [typescript](https://www.typescriptlang.org/) 来将它编译成 CommonJS 。
+:::
+
+### package.json
+
+为了把 Package 发布到 NPM 上，[package.json](https://docs.npmjs.com/cli/v6/configuring-npm/package-json) 文件是必需的：
+
+```json
+{
+  "name": "vuepress-theme-foo",
+  "version": "1.0.0",
+  "keywords": [
+    "vuepress-theme",
+  ],
+  "main": "lib/index.js",
+  "files": [
+    "lib"
+  ]
+}
+```
+
+- 将 `name` 按照约定命名： `vuepress-theme-xxx` 或 `@org/vuepress-theme-xxx` 。
+- 在 `keywords` 中包含 `vuepress-theme` ，这样用户可以在 NPM 上搜索到你的主题。
+- 将 `main` 设为主题入口文件。
+- 设置 `files` ，仅发布 `lib` 目录下的文件。
+
+### 布局
+
+主题必须提供至少两个布局：`Layout` 和 `404` 。
+
+`Layout` 布局应该包含 [Content](../../reference/components.md#content) 组件来展示 Markdown 内容。
+
+```vue
+<template>
+  <div>
+    <Content />
+  </div>
+</template>
+```
+
+`404` 布局会被用于 `404.html` 页面：
+
+```vue
+<template>
+  <div>404 Not Found</div>
+</template>
+```
+
+你可以提供多个布局，用户可以通过 [layout](../../reference/frontmatter.md#layout) Frontmatter 来修改布局。

docs/zh/reference/frontmatter.md

@@ -163,3 +163,5 @@ permalinkPattern: :year/:month/:day/:slug.html
 - 详情：
 
   页面的布局。
+
+  布局是由主题提供的。如果你不指定该 Frontmatter ，则会使用默认布局。主题可能会提供其他布局，你应该参考主题文档来获取详细指引。

docs/zh/reference/theme-api.md

@@ -37,7 +37,7 @@ VuePress 主题同样是一个插件，因此主题 API 可以接收 [插件 API
 
   它还可以接收一个普通对象，其键是布局名称，值是布局文件的绝对路径。
 
-  一个主题必须至少有两个布局： `Layout` 和 `NotFound` 。
+  一个主题必须至少有两个布局： `Layout` 和 `404` 。
 
 - 示例：
 
@@ -46,7 +46,7 @@ VuePress 主题同样是一个插件，因此主题 API 可以接收 [插件 API
 ```bash
 layouts
 ├─ Layout.vue
-├─ NotFound.vue
+├─ 404.vue
 └─ FooBar.vue
 ```
 
@@ -64,7 +64,7 @@ module.exports = {
 module.exports = {
   layouts: {
     Layout: path.resolve(__dirname, 'path/to/layouts/Layout.vue'),
-    NotFound: path.resolve(__dirname, 'path/to/layouts/NotFound.vue'),
+    404: path.resolve(__dirname, 'path/to/layouts/404.vue'),
     FooBar: path.resolve(__dirname, 'path/to/layouts/FooBar.vue'),
   },
 }
@@ -91,9 +91,9 @@ module.exports = {
   // 继承默认主题
   extends: '@vuepress/theme-default',
 
-  // 覆盖 `NotFound` 布局
+  // 覆盖 `404` 布局
   layouts: {
-    NotFound: path.resolve(__dirname, 'path/to/NotFound.vue'),
+    404: path.resolve(__dirname, 'path/to/404.vue'),
   },
 }
 ```