docs: fix English grammatical anomalies, typos, and punctuation. (#2491)

Author: koitsu

packages/docs/docs/guide/assets.md

@@ -2,15 +2,15 @@
 
 ## Relative URLs
 
-All Markdown files are compiled into Vue components and processed by webpack, so you can and **should prefer** referencing any asset using relative URLs:
+All Markdown files are compiled into Vue components and processed by [webpack](http://webpack.js.org/). You can, **and should **, reference any assets using relative URLs:
 
 ``` md
 ![An image](./image.png)
 ```
 
 This would work the same way as in `*.vue` file templates. The image will be processed with `url-loader` and `file-loader`, and copied to appropriate locations in the generated static build.
 
-Also, you can use the `~` prefix to explicitly specify this is a webpack module request, allowing you to reference files with webpack aliases or from npm dependencies:
+You can also use the `~` prefix to explicitly specify this is a webpack module request, allowing you to reference files with webpack aliases or from npm dependencies:
 
 ``` md
 ![Image from alias](~@alias/image.png)
@@ -33,13 +33,13 @@ module.exports = {
 
 ## Public Files
 
-Sometimes you may need to provide static assets that are not directly referenced in any of your Markdown or theme components - for example, favicons and PWA icons. In such cases, you can put them inside `.vuepress/public` and they will be copied to the root of the generated directory.
+Sometimes you may need to provide static assets that are not directly referenced in any of your Markdown or theme components (for example, favicons and PWA icons). In such cases, you can put them inside `.vuepress/public` and they will be copied to the root of the generated directory.
 
 ## Base URL
 
 If your site is deployed to a non-root URL, you will need to set the `base` option in `.vuepress/config.js`. For example, if you plan to deploy your site to `https://foo.github.io/bar/`, then `base` should be set to `"/bar/"` (it should always start and end with a slash).
 
-With a base URL, to reference an image in `.vuepress/public`, you’d have to use URLs like `/bar/image.png`. Yet, this is brittle if you ever decide to change the `base` later. To help with that, VuePress provides a built-in helper `$withBase` (injected onto Vue’s prototype) that generates the correct path:
+With a base URL, to reference an image in `.vuepress/public`, you’d have to use URLs like `/bar/image.png`. But this is brittle if you ever decide to change the `base`. To help with that, VuePress provides a built-in helper `$withBase` (injected onto Vue’s prototype) that generates the correct path:
 
 ``` vue
 <img :src="$withBase('/foo.png')" alt="foo">

packages/docs/docs/guide/basic-config.md

@@ -2,7 +2,7 @@
 
 ## Config File
 
-Without any configuration, the page is pretty minimal, and the user has no way to navigate around the site. To customize your site, let’s first create a `.vuepress` directory inside your docs directory. This is where all VuePress-specific files will be placed in. Your project structure is probably like this:
+Without any configuration, the page is pretty minimal, and the user has no way to navigate around the site. To customize your site, let’s first create a `.vuepress` directory inside your docs directory. This is where all VuePress-specific files will be placed. Your project structure is probably like this:
 
 ```
 .
@@ -22,7 +22,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.
+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 on all pages.
 
 Check out the [Config Reference](../config/README.md) for a full list of options.
 
@@ -38,7 +38,7 @@ To develop a custom theme, see [Writing a theme](../theme/writing-a-theme.md).
 
 ## App Level Enhancements
 
-Since the VuePress app is a standard Vue app, you can apply app-level enhancements by creating a file `.vuepress/enhanceApp.js`, which will be imported into the app if it’s present. The file should `export default` a hook function which will receive an object containing some app-level values. You can use this hook to install extra Vue plugins, register global components, or add extra router hooks:
+Since the VuePress app is a standard Vue app, you can apply app-level enhancements by creating a file `.vuepress/enhanceApp.js`, which will be imported into the app if present. The file should `export default` a hook function which will receive an object containing some app-level values. You can use this hook to install extra Vue plugins, register global components, or add extra router hooks:
 
 ``` js
 // async function is also supported, too

packages/docs/docs/guide/deploy.md

@@ -16,13 +16,13 @@ The following guides are based on some shared assumptions:
 
 ## GitHub Pages
 
-1. Set correct `base` in `docs/.vuepress/config.js`.
+1. Set the correct `base` in `docs/.vuepress/config.js`.
 
    If you are deploying to `https://<USERNAME>.github.io/`, you can omit `base` as it defaults to `"/"`.
 
-   If you are deploying to `https://<USERNAME>.github.io/<REPO>/`, (that is your repository is at `https://github.com/<USERNAME>/<REPO>`), set `base` to `"/<REPO>/"`.
+   If you are deploying to `https://<USERNAME>.github.io/<REPO>/`, e.g. your repository is at `https://github.com/<USERNAME>/<REPO>`, then set `base` to `"/<REPO>/"`.
 
-2. Inside your project, create `deploy.sh` with the following content (with highlighted lines uncommented appropriately) and run it to deploy:
+2. Inside your project, create `deploy.sh` with the following content (with highlighted lines uncommented appropriately), and run it to deploy:
 
 ``` bash{13,20,23}
 #!/usr/bin/env sh
@@ -58,17 +58,17 @@ You can also run the above script in your CI setup to enable automatic deploymen
 
 ### GitHub Pages and Travis CI
 
-1. Set correct `base` in `docs/.vuepress/config.js`.
+1. Set the correct `base` in `docs/.vuepress/config.js`.
 
    If you are deploying to `https://<USERNAME or GROUP>.github.io/`, you can omit `base` as it defaults to `"/"`.
 
-   If you are deploying to `https://<USERNAME or GROUP>.github.io/<REPO>/`, (that is your repository is at `https://github.com/<USERNAME>/<REPO>`), set `base` to `"/<REPO>/"`.
+   If you are deploying to `https://<USERNAME or GROUP>.github.io/<REPO>/`, e.g. your repository is at `https://github.com/<USERNAME>/<REPO>`, then set `base` to `"/<REPO>/"`.
 
 2. Create a file named `.travis.yml` in the root of your project.
 
 3. Run `yarn` or `npm install` locally and commit the generated lockfile (i.e. `yarn.lock` or `package-lock.json`).
 
-4. Use GitHub Pages deploy provider template and follow the [travis documentation](https://docs.travis-ci.com/user/deployment/pages/).
+4. Use the GitHub Pages deploy provider template, and follow the [Travis CI documentation](https://docs.travis-ci.com/user/deployment/pages/).
 
 ``` yaml
 language: node_js
@@ -90,15 +90,15 @@ deploy:
 
 ### GitLab Pages and GitLab CI
 
-1. Set correct `base` in `docs/.vuepress/config.js`.
+1. Set the correct `base` in `docs/.vuepress/config.js`.
 
    If you are deploying to `https://<USERNAME or GROUP>.gitlab.io/`, you can omit `base` as it defaults to `"/"`.
 
-   If you are deploying to `https://<USERNAME or GROUP>.gitlab.io/<REPO>/`, (that is your repository is at `https://gitlab.com/<USERNAME>/<REPO>`), set `base` to `"/<REPO>/"`.
+   If you are deploying to `https://<USERNAME or GROUP>.gitlab.io/<REPO>/`, e.g. your repository is at `https://gitlab.com/<USERNAME>/<REPO>`, then set `base` to `"/<REPO>/"`.
 
 2. Set `dest` in `.vuepress/config.js` to `public`.
 
-3. Create a file called `.gitlab-ci.yml` in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content.
+3. Create a file called `.gitlab-ci.yml` in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content:
 
 ``` yaml
 image: node:9.11.1
@@ -126,7 +126,7 @@ pages:
 - **Build Command:** `yarn docs:build` or `npm run docs:build`
 - **Publish directory:** `docs/.vuepress/dist`
 
-2. Hit the deploy button!
+2. Hit the deploy button.
 
 ## Google Firebase
 
@@ -153,31 +153,31 @@ pages:
 }
 ```
 
-3. After running `yarn docs:build` or `npm run docs:build`, deploy with the command `firebase deploy`.
+3. After running `yarn docs:build` or `npm run docs:build`, deploy using the command `firebase deploy`.
 
 ## Surge
 
 1. First install [surge](https://www.npmjs.com/package/surge), if you haven’t already.
 
 2. Run `yarn docs:build` or `npm run docs:build`.
 
-3. Deploy to surge, by typing `surge docs/.vuepress/dist`.
+3. Deploy to surge by typing `surge docs/.vuepress/dist`.
 
 You can also deploy to a [custom domain](http://surge.sh/help/adding-a-custom-domain) by adding `surge docs/.vuepress/dist yourdomain.com`.
 
 ## Heroku
 
-1. First install [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli).
+1. Install [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli).
 
-2. Create a Heroku account [here](https://signup.heroku.com).
+2. Create a Heroku account by [signing up](https://signup.heroku.com).
 
 3. Run `heroku login` and fill in your Heroku credentials:
 
    ``` bash
    heroku login
    ```
 
-4. Create a file called `static.json` in the root of your project with the content below:
+4. Create a file called `static.json` in the root of your project with the below content:
 
    `static.json`:
    ```json
@@ -186,7 +186,7 @@ You can also deploy to a [custom domain](http://surge.sh/help/adding-a-custom-do
    }
    ```
 
-This is the configuration of your site. See more at [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static).
+This is the configuration of your site; read more at [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static).
 
 5. Set up your Heroku git remote:
 
@@ -203,7 +203,7 @@ heroku apps:create example
 heroku buildpacks:set https://github.com/heroku/heroku-buildpack-static.git
 ```
 
-6. Deploying Your Site
+6. Deploy your site:
 
 ``` bash
 # publish site
@@ -215,4 +215,4 @@ heroku open
 
 ## Vercel
 
-Please check out [Creating and Deploying a VuePress App with Vercel](https://vercel.com/guides/deploying-vuepress-to-vercel).
+See [Creating and Deploying a VuePress App with Vercel](https://vercel.com/guides/deploying-vuepress-to-vercel).

packages/docs/docs/guide/directory-structure.md

@@ -1,6 +1,6 @@
 # Directory Structure
 
-VuePress follows the principle of **"Convention is better than configuration"**, the recommended document structure is as follows:
+VuePress follows the principle of **"Convention is better than configuration"**. The recommended structure is as follows:
 
 <!-- textlint-disable terminology -->
 
@@ -35,7 +35,7 @@ VuePress follows the principle of **"Convention is better than configuration"**,
 Please note the capitalization of the directory name.
 :::
 
-- `docs/.vuepress`: It’s used to store global configuration, components, static resources, etc.
+- `docs/.vuepress`: Used to store global configuration, components, static resources, etc.
 - `docs/.vuepress/components`: The Vue components in this directory will be automatically registered as global components.
 - `docs/.vuepress/theme`: Used to store local theme.
 - `docs/.vuepress/styles`: Stores style related files.
@@ -54,7 +54,7 @@ When customizing `templates/ssr.html`, or `templates/dev.html`, it’s best to e
 
 ## Default Page Routing
 
-Here we take `docs` directory as the `targetDir` (See [Command-line Interface](../api/cli.md#usage)), and all the "Relative Path" below are relative to `docs` directory. Add `scripts` in `package.json` which is located in the project root directory:
+Here we use the `docs` directory as the `targetDir` (see [Command-line Interface](../api/cli.md#usage)). All the "Relative Paths" below are relative to the `docs` directory. Add `scripts` in `package.json` which is located in your project's root directory:
 
 ```json
 {

packages/docs/docs/guide/frontmatter.md

@@ -1,6 +1,6 @@
 # Frontmatter
 
-Any Markdown file that contains a YAML frontmatter block will be processed by [gray-matter](https://github.com/jonschlinkert/gray-matter). The frontmatter must be the first thing in the Markdown file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example:
+Any Markdown file that contains a YAML frontmatter block will be processed by [gray-matter](https://github.com/jonschlinkert/gray-matter). The frontmatter must be at the top of the Markdown file, and must take the form of valid YAML set between triple-dashed lines. Example:
 
 ```markdown
 ---
@@ -9,7 +9,7 @@ lang: en-US
 ---
 ```
 
-Between these triple-dashed lines, you can set predefined variables (see [below](#predefined-variables) for a reference), or even create custom ones of your own. These variables will then be available to you through the  <code>[$frontmatter](./global-computed.md#frontmatter)</code> variable.
+Between the triple-dashed lines, you can set [predefined variables](#predefined-variables), or even create custom ones of your own. These variables can be used via the <code>[$frontmatter](./global-computed.md#frontmatter)</code> variable.
 
 Here’s an example of how you could use it in your Markdown file:
 
@@ -26,7 +26,7 @@ My blog post is written in {{ $frontmatter.language }}.
 
 ## Alternative frontmatter Formats
 
-VuePress also supports JSON or [TOML](https://github.com/toml-lang/toml) frontmatter.
+VuePress also supports JSON and [TOML](https://github.com/toml-lang/toml) frontmatter syntax.
 
 JSON frontmatter needs to start and end in curly braces:
 
@@ -56,21 +56,21 @@ lang = "en-US"
 - Type: `string`
 - Default: `h1_title || siteConfig.title`
 
-Title of current page.
+Title of the current page.
 
 ### lang
 
 - Type: `string`
 - Default: `en-US`
 
-Language of current page.
+Language of the current page.
 
 ### description
 
 - Type: `string`
 - Default: `siteConfig.description`
 
-Description of current page.
+Description of the current page.
 
 ### layout
 
@@ -84,7 +84,7 @@ Set the layout component of the current page.
 - Type: `string`
 - Default: `siteConfig.permalink`
 
-Refer to: [Permalinks](./permalinks.md).
+See [Permalinks](./permalinks.md) for details.
 
 ### metaTitle
 
@@ -117,39 +117,39 @@ meta:
 - Type: `boolean`
 - Default: `undefined`
 
-See: [Default Theme Config > Disable the Navbar](../theme/default-theme-config.md#disable-the-navbar).
+See [Default Theme Config > Disable the Navbar](../theme/default-theme-config.md#disable-the-navbar) for details.
 
 ### sidebar
 
 - Type: `boolean|'auto'`
 - Default: `undefined`
 
-See: [Default Theme Config > Sidebar](../theme/default-theme-config.md#sidebar).
+See [Default Theme Config > Sidebar](../theme/default-theme-config.md#sidebar) for details.
 
 ### prev
 
 - Type: `boolean|string`
 - Default: `undefined`
 
-See: [Default Theme Config > Prev / Next Links](../theme/default-theme-config.md#prev-next-links).
+See [Default Theme Config > Prev / Next Links](../theme/default-theme-config.md#prev-next-links) for details.
 
 ### next
 
 - Type: `boolean|string`
 - Default: `undefined`
 
-See: [Default Theme Config > Prev / Next Links](../theme/default-theme-config.md#prev-next-links).
+See [Default Theme Config > Prev / Next Links](../theme/default-theme-config.md#prev-next-links) for details.
 
 ### search
 
 - Type: `boolean`
 - Default: `undefined`
 
-See: [Default Theme Config > Built-in Search](../theme/default-theme-config.html#built-in-search).
+See [Default Theme Config > Built-in Search](../theme/default-theme-config.html#built-in-search) for details.
 
 ### tags
 
 - Type: `array`
 - Default: `undefined`
 
-See: [Default Theme Config > Built-in Search](../theme/default-theme-config.html#built-in-search).
+See [Default Theme Config > Built-in Search](../theme/default-theme-config.html#built-in-search). for details.

packages/docs/docs/guide/getting-started.md

@@ -61,7 +61,7 @@ This section will help you build a basic VuePress documentation site from ground
 
 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.
+   This step is optional but highly recommended, the rest of the documentation will assume those scripts being added.
 
    ``` json
    {
@@ -82,6 +82,6 @@ This section will help you build a basic VuePress documentation site from ground
 
 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.
 
-Once you’re familiar with those concepts mentioned above, learn about how to enrich your content with [static assets](assets.html), [Markdown extensions](markdown.html) and [vue components](using-vue.html).
+Once you’re familiar with those concepts mentioned above, learn how to enrich your content with [static assets](assets.html), [Markdown extensions](markdown.html) and [vue components](using-vue.html).
 
-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.
+And when your documentation site starts to take shape, be sure to read about [multi-language support](i18n.html) and the [deployment guide](deploy.html).

packages/docs/docs/guide/global-computed.md

@@ -1,10 +1,10 @@
 # Global Computed
 
-In VuePress, some core [computed](https://vuejs.org/v2/guide/computed.html#Computed-Properties) properties are built-in for use by [default theme](../theme/default-theme-config.md) or custom themes.
+In VuePress, some core [computed properties](https://vuejs.org/v2/guide/computed.html#Computed-Properties) can be used by the [default theme](../theme/default-theme-config.md) or custom themes.
 
 ## $site
 
-This is the `$site` value of the site you see now:
+This is the `$site` value of the site you're currently reading:
 
 ``` json
 {
@@ -25,7 +25,7 @@ This is the `$site` value of the site you see now:
 
 ## $page
 
-This is the `$page` value of the page you see now:
+This is the `$page` value of the page you're currently reading:
 
 ``` json
 {
@@ -56,19 +56,15 @@ Reference of [$page](#page).frontmatter.
 
 ## $lang
 
-The language of the current page, the default value is `en-US`.
+The language of the current page. Default: `en-US`.
 
-**Also see:**
-
-- [Internationalization](../guide/i18n.md)
+For more information, see [Internationalization](../guide/i18n.md).
 
 ## $localePath
 
-The locale path prefix for the current page, the default value is `/`.
-
-**Also see:**
+The locale path prefix for the current page. Default: `/`.
 
-- [Internationalization](../guide/i18n.md)
+For more information, see [Internationalization](../guide/i18n.md).
 
 ## $title
 
@@ -80,4 +76,4 @@ The `content` value of the `<meta name= "description" content= "...">` for the c
 
 ## $themeConfig
 
-That is `siteConfig.themeConfig`。
+Refers to `siteConfig.themeConfig`.