docs: add guide for authoring a plugin

Author: meteorlxy

docs/guide/advanced/plugin.md

@@ -1,3 +1,97 @@
 # Writing a Plugin
 
-> TODO
+::: tip
+Before reading this guide, you'd better learn the VuePress [architecture](./architecture.md) first.
+:::
+
+A VuePress plugin is a plain JavaScript object that satisfies the [Plugin API](../../reference/plugin-api.md), which is called a *Plugin Object*.
+
+If a plugin wants to receive user options, it could be a function that returns a *Plugin Object*, which is called a *Plugin Function*.
+
+<CodeGroup>
+  <CodeGroupItem title="Plugin Object" active>
+
+```js
+const fooPlugin = {
+  name: 'vuepress-plugin-foo',
+  // ...
+}
+```
+
+  </CodeGroupItem>
+
+  <CodeGroupItem title="Plugin Function">
+
+```js
+const fooPlugin = (options, app) => {
+  return {
+    name: 'vuepress-plugin-foo',
+    // ...
+  }
+}
+```
+
+  </CodeGroupItem>
+</CodeGroup>
+
+## Creating a Plugin Package
+
+The typical structure of a plugin package is as follow:
+
+```bash
+vuepress-plugin-foo
+├─ lib
+│  └─ index.js
+└─ package.json
+```
+
+### Plugin Entry
+
+The `lib/index.js` file is the plugin entry, which should export the plugin directly:
+
+<CodeGroup>
+  <CodeGroupItem title="CJS" active>
+
+```js
+module.export = fooPlugin
+```
+
+  </CodeGroupItem>
+
+  <CodeGroupItem title="ESM">
+
+```js
+export default fooPlugin
+```
+
+  </CodeGroupItem>
+</CodeGroup>
+
+::: tip
+Notice that the plugin 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-plugin-foo",
+  "version": "1.0.0",
+  "keywords": [
+    "vuepress-plugin",
+  ],
+  "main": "lib/index.js",
+  "files": [
+    "lib"
+  ]
+}
+```
+
+- 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 `main` to the plugin entry file.
+- Set `files` to only publish those files inside `lib` directory.

docs/zh/guide/advanced/plugin.md

@@ -1,3 +1,97 @@
 # 开发插件
 
-> TODO
+::: tip
+在阅读该指南之前，你最好先了解一下 VuePress 的 [架构](./architecture.md) 。
+:::
+
+VuePress 插件是一个符合 [Plugin API](../../reference/plugin-api.md) 的普通 JavaScript 对象，称之为 *插件对象* 。
+
+如果插件想要接收用户配置项，那么它可以是一个返回值为 *插件对象* 的函数，称之为 *插件函数* 。
+
+<CodeGroup>
+  <CodeGroupItem title="插件对象" active>
+
+```js
+const fooPlugin = {
+  name: 'vuepress-plugin-foo',
+  // ...
+}
+```
+
+  </CodeGroupItem>
+
+  <CodeGroupItem title="插件函数">
+
+```js
+const fooPlugin = (options, app) => {
+  return {
+    name: 'vuepress-plugin-foo',
+    // ...
+  }
+}
+```
+
+  </CodeGroupItem>
+</CodeGroup>
+
+## 创建一个插件 Package
+
+一个典型的插件 Package 的结构如下所示：
+
+```bash
+vuepress-plugin-foo
+├─ lib
+│  └─ index.js
+└─ package.json
+```
+
+### 插件入口
+
+`lib/index.js` 文件是插件入口，它应当直接导出插件：
+
+<CodeGroup>
+  <CodeGroupItem title="CJS" active>
+
+```js
+module.export = fooPlugin
+```
+
+  </CodeGroupItem>
+
+  <CodeGroupItem title="ESM">
+
+```js
+export default fooPlugin
+```
+
+  </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-plugin-foo",
+  "version": "1.0.0",
+  "keywords": [
+    "vuepress-plugin",
+  ],
+  "main": "lib/index.js",
+  "files": [
+    "lib"
+  ]
+}
+```
+
+- 将 `name` 按照约定命名： `vuepress-plugin-xxx` 或 `@org/vuepress-plugin-xxx` 。
+- 在 `keywords` 中包含 `'vuepress-plugin'` ，这样用户可以在 NPM 上搜索到你的插件。
+- 将 `main` 设为插件入口文件。
+- 设置 `files` ，仅发布 `lib` 目录下的文件。