docs: api (#1397)

Author: shigma

Diff for: packages/docs/docs/.vuepress/config.js

@@ -43,6 +43,7 @@ module.exports = ctx => ({
         lastUpdated: 'Last Updated',
         nav: require('./nav/en'),
         sidebar: {
+          '/api/': getApiSidebar(),
           '/guide/': getGuideSidebar('Guide', 'Advanced'),
           '/plugin/': getPluginSidebar('Plugin', 'Introduction', 'Official Plugins'),
           '/theme/': getThemeSidebar('Theme', 'Introduction'),
@@ -55,6 +56,7 @@ module.exports = ctx => ({
         lastUpdated: '上次更新',
         nav: require('./nav/zh'),
         sidebar: {
+          '/zh/api/': getApiSidebar(),
           '/zh/guide/': getGuideSidebar('指南', '深入'),
           '/zh/plugin/': getPluginSidebar('插件', '介绍', '官方插件'),
           '/zh/theme/': getThemeSidebar('主题', '介绍')
@@ -87,6 +89,15 @@ module.exports = ctx => ({
   ],
 })
 
+function getApiSidebar () {
+  return [
+    '',
+    'config',
+    'cli',
+    'node'
+  ]
+}
+
 function getGuideSidebar (groupA, groupB) {
   return [
     {

Diff for: packages/docs/docs/.vuepress/nav/en.js

@@ -4,8 +4,8 @@ module.exports = [
     link: '/guide/',
   },
   {
-    text: 'Config Reference',
-    link: '/config/'
+    text: 'API',
+    link: '/api/'
   },
   {
     text: 'Plugin',

Diff for: packages/docs/docs/.vuepress/nav/zh.js

@@ -4,8 +4,8 @@ module.exports = [
     link: '/zh/guide/',
   },
   {
-    text: '配置',
-    link: '/zh/config/'
+    text: 'API',
+    link: '/zh/api/'
   },
   {
     text: '插件',

Diff for: packages/docs/docs/api/README.md

@@ -0,0 +1,7 @@
+# API
+
+We offer a variety of ways to use VuePress. This section will cover the following two sections:
+
+- [Config Reference](./config.md)
+- [Node.js API](./node.md)
+- [Command Line Interface](./cli.md)

Diff for: packages/docs/docs/api/cli.md

@@ -0,0 +1,45 @@
+# Command Line Interface
+
+## Usage
+
+```bash
+vuepress <command> targetDir [options]
+```
+
+## build
+
+Build dir as a static site.
+
+### -p, --port `<port>`
+See [port](./config.md#port).
+
+### -t, --temp `<temp>`
+See [temp](./config.md#temp).
+
+### -c, --cache [cache]
+### -no--cache [cache]
+See [cache](./config.md#cache).
+
+### --debug
+Start development server in debug mode.
+
+### --silent
+Start development server in silent mode.
+
+## dev
+
+Start a development server. All options from `vuepress build` are available. And there are several options specifically for dev:
+
+### --host `<host>`
+See [host](../config.md#host).
+
+### --open
+Open browser when ready.
+
+## eject
+
+Copy the default theme into `.vuepress/theme` for customization.
+
+## more commands
+
+You can create a custom command with [extendCli](../plugin/option-api.md#extendcli).

Diff for: packages/docs/docs/config/README.md renamed to packages/docs/docs/api/config.md

@@ -1,5 +1,5 @@
 ---
-sidebar: auto
+sidebarDepth: 3
 ---
 
 # Config Reference
@@ -65,6 +65,13 @@ Specify the host to use for the dev server.
 
 Specify the port to use for the dev server.
 
+### temp
+
+- Type: `number`
+- Default: `@vuepress/core/.temp`
+
+Specify the temporary directory for client. 
+
 ### dest
 
 - Type: `string`

Diff for: packages/docs/docs/api/node.md

@@ -0,0 +1,57 @@
+# Node.js API
+
+```js
+const vuepress = require('vuepress')
+```
+
+## Global Methods
+
+### vuepress.dev
+
+Start a development server.
+
+### vuepress.build
+
+Build dir as a static site.
+
+### vuepress.eject
+
+Copy the default theme into `.vuepress/theme` for customization.
+
+### vuepress.createApp
+
+Create a VuePress App for for customization. For example,
+
+```js
+const app = vuepress.createApp(/* options */)
+app.process().then(() => {
+  console.log('ready!')
+  app.dev()
+})
+```
+
+## App Options
+
+### options.sourceDir
+
+Specify the source directory for VuePress.
+
+### options.theme
+
+See [theme](../config.md#theme).
+
+### options.plugins
+
+See [plugins](../config.md#plugins).
+
+### options.temp
+
+See [temp](../config.md#temp).
+
+### options.dest
+
+See [dest](../config.md#dest).
+
+### options.siteConfig
+
+See [siteConfig](../config.md).

Diff for: packages/docs/docs/guide/assets.md

@@ -17,7 +17,7 @@ In addition, you can use the `~` prefix to explicitly indicate this is a webpack
 ![Image from dependency](~some-dependency/image.png)
 ```
 
-webpack aliases can be configured via [configureWebpack](/config/#configurewebpack) in `.vuepress/config.js`. Example:
+webpack aliases can be configured via [configureWebpack](../api/config.md#configurewebpack) in `.vuepress/config.js`. Example:
 
 ``` js
 module.exports = {

Diff for: packages/docs/docs/guide/basic-config.md

@@ -24,7 +24,7 @@ module.exports = {
 
 If you've got the dev server running, you should see the page now has a header with the title and a search box. VuePress comes with built-in headers-based search - it automatically builds a simple search index from the title, `h2` and `h3` headers from all the pages.
 
-Consult the [Config Reference](../config/README.md) for a full list of options.
+Consult the [Config Reference](../api/config.md) for a full list of options.
 
 ::: tip Alternative Config Formats
 You can also use YAML (`.vuepress/config.yml`) or TOML (`.vuepress/config.toml`) formats for the configuration file.

Diff for: packages/docs/docs/guide/directory-structure.md

@@ -60,7 +60,7 @@ For the above directory structure, the default page routing paths are as follows
 
 **Also see:** 
 
-- [Config](../config/README.md)
-- [Theme](../theme/README.md)
+- [Config](../api/config.md)
+- [Theme](../theme/)
 - [Default Theme Config](../theme/default-theme-config.md)
 

Diff for: packages/docs/docs/guide/markdown.md

@@ -2,7 +2,7 @@
 
 ## Header Anchors
 
-Headers automatically get anchor links applied. Rendering of anchors can be configured using the [`markdown.anchor`](../config/README.md#markdown-anchor) option.
+Headers automatically get anchor links applied. Rendering of anchors can be configured using the [`markdown.anchor`](../api/config.md#markdown-anchor) option.
 
 ## Links
 
@@ -53,7 +53,7 @@ Outbound links automatically gets `target="_blank" rel="noopener noreferrer"`:
 - [vuejs.org](https://vuejs.org)
 - [VuePress on GitHub](https://github.com/vuejs/vuepress)
 
-You can customize the attributes added to external links by setting [config.markdown.externalLinks](../config/README.md#markdown-externallinks).
+You can customize the attributes added to external links by setting [config.markdown.externalLinks](../api/config.md#markdown-externallinks).
 
 ## Front Matter
 
@@ -122,7 +122,7 @@ or
 
 [[toc]]
 
-Rendering of TOC can be configured using the [`markdown.toc`](../config/README.md#markdown-toc) option, or as props of [TOC component](./using-vue.md#toc), like `<TOC list-type="ol" :include-level="[2, Infinity]"/>`.
+Rendering of TOC can be configured using the [`markdown.toc`](../api/config.md#markdown-toc) option, or as props of [TOC component](./using-vue.md#toc), like `<TOC list-type="ol" :include-level="[2, Infinity]"/>`.
 
 ## Custom Containers
 

Diff for: packages/docs/docs/guide/using-vue.md

@@ -168,7 +168,7 @@ yarn add -D pug pug-plain-loader
 ::: tip
 If you are a Stylus user, you don't need to install `stylus` and `stylus-loader` in your project because VuePress uses Stylus internally.
 
-For pre-processors that do not have built-in webpack config support, you will need to [extend the internal webpack config](../config/README.md#configurewebpack) in addition to installing the necessary dependencies.
+For pre-processors that do not have built-in webpack config support, you will need to [extend the internal webpack config](../api/config.md#configurewebpack) in addition to installing the necessary dependencies.
 :::
 
 ## Script & Style Hoisting

Diff for: packages/docs/docs/miscellaneous/migration-guide.md

@@ -65,13 +65,13 @@ See: [@vuepress/plugin-pwa > Migration from 0.x](../plugin/official/plugin-pwa.m
 Replaced by `.vuepress/styles/palette.styl`.
 
 ::: upgrade
-See: [Config > palette.styl](../config/README.md#palette-styl)
+See: [Config > palette.styl](../api/config.md#palette-styl)
 :::
 
 ### `.vuepress/style.styl` <Badge text="replaced"/>
 
 Replaced by `.vuepress/styles/index.styl`.
 
 ::: upgrade
-See: [Config > index.styl](../config/README.md#index-styl)
+See: [Config > index.styl](../api/config.md#index-styl)
 :::

Diff for: packages/docs/docs/plugin/context-api.md

@@ -46,7 +46,7 @@ Output path.
 
 - Type: `string`
 
-See: [base](../config/README.md#base).
+See: [base](../api/config.md#base).
 
 ## ctx.writeTemp
 

Diff for: packages/docs/docs/plugin/official/plugin-nprogress.md

@@ -36,4 +36,4 @@ $nprogressColor = red
 
 **Also see:**
 
-- [Config Reference > Styling](../../config/#styling)
+- [Config Reference > Styling](../../api/config.md#styling)

Diff for: packages/docs/docs/theme/default-theme-config.md

@@ -379,7 +379,7 @@ Note that it's `off` by default. If given a `string`, it will be displayed as a
 The `themeConfig.serviceWorker` option allows you to configure the service worker.
 
 ::: tip
-Please do not confuse this option with [Config > serviceWorker](../config/README.md#serviceworker), [Config > serviceWorker](../config/README.md#serviceworker) is **site-level**, while this option is **theme-level**.
+Please do not confuse this option with [Config > serviceWorker](../api/config.md#serviceworker), [Config > serviceWorker](../api/config.md#serviceworker) is **site-level**, while this option is **theme-level**.
 :::
 
 ### Popup UI to refresh contents <Badge text="0.13.0+"/> <Badge text="beta" type="warn"/>

Diff for: packages/docs/docs/theme/writing-a-theme.md

@@ -29,7 +29,7 @@ The compiled content of the current `.md` file being rendered will be available
 
 ## Directory Structure
 
-Just one `Layout.vue` might not be enough, and you might also want to define more layout components in the theme for using on different pages. You may also want to customize the [palette](../config/README.md#palette-styl), and even apply some plugins.
+Just one `Layout.vue` might not be enough, and you might also want to define more layout components in the theme for using on different pages. You may also want to customize the [palette](../api/config.md#palette-styl), and even apply some plugins.
 
 So it's time to reorganize your theme, an agreed theme directory structure is as follows:
 

Diff for: packages/docs/docs/zh/api/README.md

@@ -0,0 +1,7 @@
+# API
+
+我们提供了多种使用 VuePress 的方式。这一节将包括下面三个部分：
+
+- [配置说明](./config.md)
+- [Node.js API](./node.md)
+- [命令行接口](./cli.md)

Diff for: packages/docs/docs/zh/api/cli.md

@@ -0,0 +1,45 @@
+# 命令行接口
+
+## 基本用法
+
+```bash
+vuepress <command> targetDir [options]
+```
+
+## build
+
+在指定的目录生成一个静态站点。
+
+### -p, --port `<port>`
+查看 [port](./config.md#port)。
+
+### -t, --temp `<temp>`
+查看 [temp](./config.md#temp)。
+
+### -c, --cache [cache]
+### -no--cache [cache]
+查看 [cache](./config.md#cache)。
+
+### --debug
+以调试模式启动开发服务器。
+
+### --silent
+以安静模式启动开发服务器。
+
+## dev
+
+启动一个开发服务器。来自 `vuepress build` 的所有选项都可用。除此以外，还有几个专门针对 dev 的选项：
+
+### --host `<host>`
+查看 [host](./config.md#host)。
+
+### --open
+当服务端准备就绪时自动打开浏览器。
+
+## eject
+
+将默认主题复制到 `.vuepress/theme` 目录，以供自定义。
+
+## more commands
+
+你可以使用 [extendCli](../plugin/option-api.md#extendcli) 来创建自定义命令。

Diff for: packages/docs/docs/zh/config/README.md renamed to packages/docs/docs/zh/api/config.md

@@ -1,5 +1,5 @@
 ---
-sidebar: auto
+sidebarDepth: 3
 ---
 
 # 配置
@@ -63,6 +63,13 @@ module.exports = {
 
 指定 dev server 的端口。
 
+### temp
+
+- Type: `number`
+- Default: `@vuepress/core/.temp`
+
+指定客户端文件的临时目录。
+
 ### dest
 
 - 类型: `string`