docs: refine getting started (close #2111) (#2281)

* docs: getting started steps * docs: dir structure and basic config * docs: ready for review * docs: tweaks * docs: fix list-item-content-indent * docs: zh translation
vuejs · Jun 10, 2020 · 20e7329 · 20e7329
1 parent f6acb9f
commit 20e7329
Show file tree

Hide file tree

Showing 2 changed files with 83 additions and 97 deletions.
diff --git a/packages/docs/docs/guide/getting-started.md b/packages/docs/docs/guide/getting-started.md
@@ -1,69 +1,64 @@
 # Getting Started
 
-::: warning COMPATIBILITY NOTE
-VuePress requires Node.js >= 8.
+::: warning Prerequisite
+VuePress requires [Node.js](https://nodejs.org/en/) >= 8.6.
 :::
 
-## Global Installation
+This section will help you build a basic VuePress documentation site from ground up. If you already have an existing project and would like to keep documentation inside the project, start from Step 3.
 
-If you only want to play around with VuePress, you can install it globally:
+1. Create and change into a new directory
 
-``` bash
-# install globally
-yarn global add vuepress # OR npm install -g vuepress
+   ``` bash
+   mkdir vuepress-starter && cd vuepress-starter
+   ```
 
-# create the project folder
-mkdir vuepress-starter && cd vuepress-starter
+2. Initialize with your preferred package manager
 
-# create a markdown file
-echo '# Hello VuePress' > README.md
+   ``` bash
+   yarn init # npm init
+   ```
 
-# start writing
-vuepress dev
+3. Install VuePress locally
 
-# build
-vuepress build
-```
+   Globally installed VuePress is no longer recommended.
 
-## Inside an Existing Project
+   ``` bash
+   yarn add -D vuepress # npm install -D vuepress
+   ```
 
-If you have an existing project and would like to keep documentation inside the project, you should install VuePress as a local dependency. This setup also allows you to use CI or services like [Netlify](https://netlify.com) for automatic deployment on push.
+   ::: warning
+   We currently recommend using [Yarn](https://classic.yarnpkg.com/lang/en/) instead of npm when installing VuePress into an existing project that has webpack 3.x as a dependency, because npm fails to generate the correct dependency tree in this case.
+   :::
 
-``` bash
-# install as a local dependency
-yarn add -D vuepress # OR npm install -D vuepress
+4. Create your first document
 
-# create a docs directory
-mkdir docs
-# create a markdown file
-echo '# Hello VuePress' > docs/README.md
-```
+   ``` bash
+   mkdir docs && echo '# Hello VuePress' > docs/README.md
+   ```
 
-::: warning
-We currently recommend using [Yarn](https://yarnpkg.com/en/) instead of npm when installing VuePress into an existing project that has webpack 3.x as a dependency, because npm fails to generate the correct dependency tree in this case.
-:::
+5. Add some [scripts](https://classic.yarnpkg.com/en/docs/package-json#toc-scripts) to `package.json`
+
+   This step is optional but highly recommended, the rest of the documentaion will assume those scripts being added.
 
-Then, add some scripts to `package.json`:
+   ``` json
+   {
+     "scripts": {
+       "docs:dev": "vuepress dev docs",
+       "docs:build": "vuepress build docs"
+     }
+   }
+   ```
 
-``` json
-{
-  "scripts": {
-    "docs:dev": "vuepress dev docs",
-    "docs:build": "vuepress build docs"
-  }
-}
-```
+6. Serve the documentation site in the local server
 
-You can now start writing with:
+   ``` bash
+   yarn docs:dev # npm run docs:dev
+   ```
 
-``` bash
-yarn docs:dev # OR npm run docs:dev
-```
+   VuePress will start a hot-reloading development server at [http://localhost:8080](http://localhost:8080).
 
-To generate static assets, run:
+By now, you should have a basic but functional VuePress documentation site. Next, learn about VuePress’ recommended [directory structure](directory-structure.html) and the basics of [configuration](basic-config.html) in VuePress.
 
-``` bash
-yarn docs:build # OR npm run docs:build
-```
+Once you’re familiar with those concepts mentioned above, learn about how to enrich your content with [static assests](assets.html), [Markdown extensions](markdown.html) and [vue components](using-vue.html).
 
-By default, the built files will be in `.vuepress/dist`, which can be configured via the `dest` field in `.vuepress/config.js`. The built files can be deployed to any static file server. See [Deployment Guide](deploy.md) for guides on deploying to popular services.
+And when your documentation site start to take shape, check out the [multi-language support](i18n.html) and guides for [deploying](deploy.html) your site to popular services.
diff --git a/packages/docs/docs/zh/guide/getting-started.md b/packages/docs/docs/zh/guide/getting-started.md
@@ -1,73 +1,64 @@
 # 快速上手
 
-::: warning 注意
-请确保你的 Node.js 版本 >= 8。
+::: warning 前提条件
+VuePress 需要 [Node.js](https://nodejs.org/en/) >= 8.6
 :::
 
-## 全局安装
+本文会帮助你从头搭建一个简单的 VuePress 文档。如果你想在一个现有项目中使用 VuePress 管理文档，从步骤 3 开始。
 
-如果你只是想尝试一下 VuePress，你可以全局安装它：
+1. 创建并进入一个新目录
 
-``` bash
-# 安装
-yarn global add vuepress # 或者：npm install -g vuepress
+   ``` bash
+   mkdir vuepress-starter && cd vuepress-starter
+   ```
 
-# 创建项目目录
-mkdir vuepress-starter && cd vuepress-starter
+2. 使用你喜欢的包管理器进行初始化
 
-# 新建一个 markdown 文件
-echo '# Hello VuePress!' > README.md
+   ``` bash
+   yarn init # npm init
+   ```
 
-# 开始写作
-vuepress dev .
+3. 将 VuePress 安装为本地依赖
 
-# 构建静态文件
-vuepress build .
-```
+   我们已经不再推荐全局安装 VuePress
 
-## 现有项目
+   ``` bash
+   yarn add -D vuepress # npm install -D vuepress
+   ```
 
-如果你想在一个现有项目中使用 VuePress，同时想要在该项目中管理文档，则应该将 VuePress 安装为本地依赖。作为本地依赖安装让你可以使用持续集成工具，或者一些其他服务（比如 Netlify）来帮助你在每次提交代码时自动部署。
+   ::: warning 注意
+   如果你的现有项目依赖了 webpack 3.x，我们推荐使用 [Yarn](https://classic.yarnpkg.com/zh-Hans/) 而不是 npm 来安装 VuePress。因为在这种情形下，npm 会生成错误的依赖树。
+   :::
 
-``` bash
-# 将 VuePress 作为一个本地依赖安装
-yarn add -D vuepress # 或者：npm install -D vuepress
+4. 创建你的第一篇文档
 
-# 新建一个 docs 文件夹
-mkdir docs
+   ``` bash
+   mkdir docs && echo '# Hello VuePress' > docs/README.md
+   ```
 
-# 新建一个 markdown 文件
-echo '# Hello VuePress!' > docs/README.md
+5. 在 `package.json` 中添加一些 [scripts](https://classic.yarnpkg.com/zh-Hans/docs/package-json#toc-scripts)
 
-# 开始写作
-npx vuepress dev docs
-```
+   这一步骤是可选的，但我们推荐你完成它。在下文中，我们会默认这些 scripts 已经被添加。
 
-::: warning
-如果你的现有项目依赖了 webpack 3.x，推荐使用 [Yarn](https://yarnpkg.com/en/) 而不是 npm 来安装 VuePress。因为在这种情形下，npm 会生成错误的依赖树。
-:::
-
-接着，在 `package.json` 里加一些脚本:
+   ``` json
+   {
+     "scripts": {
+       "docs:dev": "vuepress dev docs",
+       "docs:build": "vuepress build docs"
+     }
+   }
+   ```
 
-``` json
-{
-  "scripts": {
-    "docs:dev": "vuepress dev docs",
-    "docs:build": "vuepress build docs"
-  }
-}
-```
+6. 在本地启动服务器
 
-然后就可以开始写作了:
+   ``` bash
+   yarn docs:dev # npm run docs:dev
+   ```
 
-``` bash
-yarn docs:dev # 或者：npm run docs:dev
-```
+   VuePress 会在 [http://localhost:8080](http://localhost:8080) 启动一个热重载的开发服务器。
 
-要生成静态的 HTML 文件，运行：
+现在，你应该已经有了一个简单可用的 VuePress 文档。接下来，了解一下推荐的 [目录结构](directory-structure.html) 和 VuePress 中的 [基本配置](basic-config.html)。
 
-``` bash
-yarn docs:build # 或者：npm run docs:build
-```
+等你了解完上文介绍的基础概念，再去学习一下如何使用 [静态资源](assets.html)，[Markdown 拓展](markdown.html) 和 [在 Markdown 中使用 Vue](using-vue.html) 来丰富你的文档内容。
 
-默认情况下，文件将会被生成在 `.vuepress/dist`，当然，你也可以通过 `.vuepress/config.js` 中的 `dest` 字段来修改，生成的文件可以部署到任意的静态文件服务器上，参考 [部署](deploy.md) 来了解更多。
+当你的文档逐渐成型的时候，不要忘记 VuePress 的 [多语言支持](i18n.html) 并了解一下如何将你的文档 [部署](deploy.html) 到任意静态文件服务器上。