docs: documentation linting (#1745)

* chore: install textlint

* chore: add textlint rules

* feat: set up configuration file and command

* fix: run textlint on files

* chore: lint .textlintrc.js

* chore: add custom terms

* chore: add comment filter

* fix: fix frontmatter term

* chore: set subjective rules to warning severity

* fix: manually fix issues

* chore: add script as pre-commit hook

.lintstagedrc

@@ -0,0 +1,3 @@
+{
+  "*.{js,vue}": ["eslint --fix", "git add"]
+}

package.json

@@ -7,6 +7,7 @@
   ],
   "description": "Minimalistic doc generator with Vue component based layout system",
   "scripts": {
+    "precommit": "lint-staged",
     "bootstrap": "yarn && lerna bootstrap && yarn tsc",
     "clean": "lerna clean && rm -rf node_modules",
     "boot": "node scripts/bootstrap.js",
@@ -24,25 +25,23 @@
     "test": "node scripts/test.js",
     "tsc": "lerna run tsc"
   },
-  "gitHooks": {
-    "pre-commit": "lint-staged"
-  },
-  "lint-staged": {
-    "*.{js,vue}": [
-      "eslint --fix",
-      "git add"
-    ]
-  },
   "devDependencies": {
+    "@types/escape-html": "^0.0.20",
+    "@types/fs-extra": "^5.0.4",
+    "@types/globby": "^9.1.0",
+    "@types/hash-sum": "^1.0.0",
+    "@types/lru-cache": "^4.1.1",
+    "@types/node": "^10.12.12",
+    "@types/semver": "^6.0.0",
     "conventional-changelog-cli": "^2.0.21",
     "eslint": "^4.19.1",
     "eslint-plugin-jest": "^21.15.1",
     "eslint-plugin-vue-libs": "^3.0.0",
+    "husky": "^3.0.2",
+    "inquirer": "^6.2.0",
     "lerna": "3.13.4",
     "lint-staged": "^8.1.5",
     "minimist": "^1.2.0",
-    "yorkie": "^2.0.0",
-    "inquirer": "^6.2.0",
     "typescript": "^3.2.2",
     "@types/node": "^10.12.12",
     "@types/lru-cache": "^4.1.1",

packages/docs/.lintstagedrc

@@ -0,0 +1,3 @@
+{
+  "docs/**/*.md": ["yarn lint-md", "git add"]
+}

packages/docs/.textlint.terms.json

@@ -0,0 +1,8 @@
+[
+  "Stylus",
+  "VuePress",
+  [
+    "front[- ]matter",
+    "frontmatter"
+  ]
+]

packages/docs/.textlintrc.js

@@ -0,0 +1,23 @@
+module.exports = {
+  rules: {
+    '@textlint-rule/no-unmatched-pair': true,
+    apostrophe: true,
+    'common-misspellings': true,
+    diacritics: true,
+    'en-capitalization': {
+      allowHeading: false
+    },
+    'stop-words': {
+      severity: 'warning'
+    },
+    terminology: {
+      terms: `${__dirname}/.textlint.terms.json`
+    },
+    'write-good': {
+      severity: 'warning'
+    }
+  },
+  filters: {
+    comments: true
+  }
+}

packages/docs/docs/api/cli.md

@@ -1,4 +1,4 @@
-# Command Line Interface
+# Command-line Interface
 
 ## Usage
 
@@ -40,7 +40,7 @@ See [host](../config/README.md#host).
 Open browser when ready.
 
 ### --no-clear-screen
-do not clear screen when dev server is ready.
+Do not clear screen when dev server is ready.
 
 ## eject
 

packages/docs/docs/api/node.md

@@ -14,7 +14,7 @@ Create a VuePress application.
 
 #### App.prototype.process: () => Promise\<void> | never
 
-A asynchronous method used to prepare the context of the current app. which contains loading pages and plugins, apply plugins, etc.
+An asynchronous method used to prepare the context of the current app, and which contains loading pages and plugins, apply plugins, etc.
 
 #### App.prototype.dev: () => Promise\<App> | never
 
@@ -27,7 +27,7 @@ Launch a build process with current app context.
 
 ### dev(\[options]): Promise\<App>
 
-Start a development server, actually it's implemented by `createApp`:
+Start a development server, actually it’s implemented by `createApp`:
 
 ```js
 async function dev (options) {
@@ -39,7 +39,7 @@ async function dev (options) {
 
 ### build(\[options]): Promise\<App>
 
-Build your source files as a static site, actually it's implemented by `createApp`:
+Build your source files as a static site, actually it’s implemented by `createApp`:
 
 ```js
 async function build (options) {
@@ -96,4 +96,4 @@ See [dest](../config/README.md#dest).
 - Type: `object`
 - Required: `{}`
 
-It's very useful when you're writing tests and don't want to depend on actual config file, for all options please head [siteConfig](../config/README.md).
+It’s useful when you’re writing tests and don’t want to depend on actual config file, for all options please head [siteConfig](../config/README.md).

packages/docs/docs/config/README.md

@@ -14,7 +14,7 @@ sidebar: auto
 - Type: `string`
 - Default: `/`
 
-The base URL the site will be deployed at. You will need to set this if you plan to deploy your site under a sub path, for example, GitHub pages. 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.
+The base URL the site will be deployed at. You will need to set this if you plan to deploy your site under a sub path, for example, GitHub pages. If you plan to deploy your site to `https://foo.github.io/bar/`, then you should set `base` to `"/bar/"`. It should always start and end with a slash.
 
 The `base` is automatically prepended to all the URLs that start with `/` in other options, so you only need to specify it once.
 
@@ -35,14 +35,14 @@ Title for the site. This will be the prefix for all page titles, and displayed i
 - Type: `string`
 - Default: `undefined`
 
-Description for the site. This will be rendered as a `<meta>` tag in the page HTML.
+Description for the site. This will render as a `<meta>` tag in the page HTML.
 
 ### head
 
 - Type: `Array`
 - Default: `[]`
 
-Extra tags to be injected to the page HTML `<head>`. Each tag can be specified in the form of `[tagName, { attrName: attrValue }, innerHTML?]`. For example, to add a custom favicon:
+Extra tags to inject into the page HTML `<head>`. You can specify each tag in the form of `[tagName, { attrName: attrValue }, innerHTML?]`. For example, to add a custom favicon:
 
 ``` js
 module.exports = {
@@ -102,10 +102,10 @@ A function to control what files should have `<link rel="preload">` resource hin
 
 VuePress uses [cache-loader](https://github.com/webpack-contrib/cache-loader) by default to greatly speed up the compilation of webpack.
 
-This option can be used to specify the path to the cache, and can also remove the cache before each build by setting it to `false`.
+You can use this option to specify the path to the cache, and can also remove the cache before each build by setting it to `false`.
 
 ::: tip
-This option can also be used through the CLI:
+You can also use this option through the CLI:
 
 ```bash
 vuepress dev docs --cache .cache # set cache path
@@ -118,7 +118,7 @@ vuepress dev docs --no-cache     # remove cache before each build.
 - Type: `Array`
 - Default: `[]`
 
-Specify extra files to be watched.
+Specify extra files to watch.
 
 You can watch any file if you want. File changes will trigger `vuepress` rebuilding and real-time updates.
 
@@ -135,9 +135,9 @@ module.exports = {
 
 ### palette.styl
 
-If you wish to apply simple color overrides to the styling of the [default preset](https://github.com/vuejs/vuepress/blob/master/packages/@vuepress/core/lib/client/style/config.styl) or define some color variables for using later, you can create an `.vuepress/styles/palette.styl` file.
+To apply simple color overrides to the styling of the [default preset](https://github.com/vuejs/vuepress/blob/master/packages/@vuepress/core/lib/client/style/config.styl) or define some color variables for using later, you can create a `.vuepress/styles/palette.styl` file.
 
-There are a few color variables you can tweak:
+There are some color variables you can tweak:
 
 ``` stylus
 // showing default values
@@ -148,12 +148,12 @@ $codeBgColor = #282c34
 ```
 
 ::: danger Note
-You should ONLY write color variables in this file. since `palette.styl` will be imported at the end of the root stylus config file, as a config, it will be used by multiple files, so once you wrote styles here, your style would be duplicated by multiple times.
+You should ONLY write color variables in this file. Since `palette.styl` will be imported at the end of the root Stylus config file, as a config, several files will use it, so once you wrote styles here, your style would be duplicated by multiple times.
 :::
 
 ### index.styl
 
-VuePress provides a convenient way to add extra styles. you can create an `.vuepress/styles/index.styl` file for that. This is a [Stylus](http://stylus-lang.com/) file but you can use normal CSS syntax as well.
+VuePress provides a convenient way to add extra styles. You can create a `.vuepress/styles/index.styl` file for that. This is a [Stylus](http://stylus-lang.com/) file but you can use normal CSS syntax as well.
 
 ```stylus
 .content {
@@ -163,7 +163,7 @@ VuePress provides a convenient way to add extra styles. you can create an `.vuep
 
 **Also see:**
 
-- [Why can't `palette.styl` and `index.styl` merge into one API?](../faq/README.md#why-can-t-palette-styl-and-index-styl-merge-into-one-api)
+- [Why can’t `palette.styl` and `index.styl` merge into one API?](../faq/README.md#why-can-t-palette-styl-and-index-styl-merge-into-one-api)
 
 ## Theming
 
@@ -196,7 +196,7 @@ Provide config options to the used theme. The options will vary depending on the
 - Type: `Object|Array`
 - Default: `undefined`
 
-Please refer to [Plugin > Using a plugin](../plugin/using-a-plugin.md) to learn how to use a plugin.
+Please check out [Plugin > Using a plugin](../plugin/using-a-plugin.md) to learn how to use a plugin.
 
 ## Markdown
 
@@ -223,7 +223,7 @@ Function for transforming [header](../miscellaneous/glossary.md#headers) texts i
 - Type: `Object`
 - Default: `{ permalink: true, permalinkBefore: true, permalinkSymbol: '#' }`
 
-Options for [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor). (Note: prefer `markdown.slugify` if you want to customize header ids.)
+Options for [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor). (Note: prefer `markdown.slugify` to customize header ids.)
 
 ### markdown.externalLinks
 
@@ -237,11 +237,11 @@ The key and value pair will be added to `<a>` tags that point to an external lin
 - Type: `Object`
 - Default: `{ includeLevel: [2, 3] }`
 
-Options for [markdown-it-table-of-contents](https://github.com/Oktavilla/markdown-it-table-of-contents). (Note: prefer `markdown.slugify` if you want to customize header ids.)
+Options for [markdown-it-table-of-contents](https://github.com/Oktavilla/markdown-it-table-of-contents). (Note: prefer `markdown.slugify` to customize header ids.)
 
 ### markdown.plugins
 
-You can install any markdown-it plugins through `markdown.plugins` option. It is similar with [using VuePress plugins](../plugin/using-a-plugin.html#using-a-plugin). You can either use Babel style or object style. The `markdown-it-` prefix is optional and can omit in the list.
+You can install any markdown-it plugins through `markdown.plugins` option. It’s similar with [using VuePress plugins](../plugin/using-a-plugin.html#using-a-plugin). You can either use Babel style or object style. The `markdown-it-` prefix is optional and can omit in the list.
 
 ``` js
 module.exports = {
@@ -256,7 +256,7 @@ module.exports = {
 }
 ```
 
-or
+Or
 
 ``` js
 module.exports = {
@@ -276,7 +276,7 @@ module.exports = {
 - Type: `Function`
 - Default: `undefined`
 
-A function to modify default config or apply additional plugins to the [markdown-it](https://github.com/markdown-it/markdown-it) instance used to render source files. e.g.
+A function to edit default config or apply extra plugins to the [markdown-it](https://github.com/markdown-it/markdown-it) instance used to render source files. For example:
 
 ``` js
 module.exports = {
@@ -306,7 +306,7 @@ VuePress comes with built-in webpack config for the CSS pre-processors listed be
 
 Options for [postcss-loader](https://github.com/postcss/postcss-loader). Note specifying this value will overwrite autoprefixer and you will need to include it yourself.
 
-### stylus
+### Stylus
 
 - Type: `Object`
 - Default: `{ preferPathResolver: 'webpack' }`
@@ -320,7 +320,7 @@ Options for [stylus-loader](https://github.com/shama/stylus-loader).
 
 Options for [sass-loader](https://github.com/webpack-contrib/sass-loader) to load `*.scss` files.
 
-### sass
+### Sass
 
 - Type: `Object`
 - Default: `{ indentedSyntax: true }`
@@ -339,7 +339,7 @@ Options for [less-loader](https://github.com/webpack-contrib/less-loader).
 - Type: `Object | Function`
 - Default: `undefined`
 
-Modify the internal webpack config. If the value is an Object, it will be merged into the final config using [webpack-merge](https://github.com/survivejs/webpack-merge); If the value is a function, it will receive the config as the 1st argument and an `isServer` flag as the 2nd argument. You can either mutate the config directly, or return an object to be merged:
+Edit the internal webpack config. If the value is an Object, it will be merged into the final config using [webpack-merge](https://github.com/survivejs/webpack-merge); If the value is a function, it will receive the config as the 1st argument and an `isServer` flag as the 2nd argument. You can either mutate the config directly, or return an object to merge:
 
 ``` js
 module.exports = {
@@ -356,7 +356,7 @@ module.exports = {
 - Type: `Function`
 - Default: `undefined`
 
-Modify the internal webpack config with [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain).
+Edit the internal webpack config with [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain).
 
 ``` js
 module.exports = {

packages/docs/docs/faq/README.md

@@ -4,13 +4,13 @@ sidebar: auto
 
 # FAQ
 
-## Why can't `palette.styl` and `index.styl` merge into one API?
+## Why can’t `palette.styl` and `index.styl` merge into one API?
 
-The `palette.styl` is responsible for global color settings. During compilation, theme color constants should be resolved by the preprocessor first and then be applied to the global context. 
+The `palette.styl` is responsible for global color settings. During compilation, theme color constants should be resolved by the preprocessor first and then be applied to the global context.
 
-But for `index.styl`. its job is to override the default styles of application. According to the priority principle of css, the later style has a higher priority, so it should be generated at the end of the CSS file. 
+But for `index.styl`, its job is to override the default styles of application. According to the priority principle of CSS, the later style has a higher priority, so it should be generated at the end of the CSS file.
 
-A simple diagram describing the stylus compiler's compilation order as follows:
+A simple diagram describing the Stylus compiler’s compilation order as follows:
 
 @flowstart
 stage1=>operation: palette.styl
@@ -22,11 +22,11 @@ stage1->stage2->stage3
 
 <br>
 
-## What's the differences between the `clientDynamicModules` and `enhanceAppFiles`?
+## What’s the differences between the `clientDynamicModules` and `enhanceAppFiles`?
 
-Let's take a look back first, both `clientDynamicModules` and `enhanceAppFiles` can generate modules with dynamic javascript code during compile time.
+Let’s take a look back first, both `clientDynamicModules` and `enhanceAppFiles` can generate modules with dynamic JavaScript code during compile time.
 
-The difference is that the files generated by `enhanceAppFiles` will be loaded and applied automatically when the application is initialized on the client side. While the files generated by `clientDynamicModules` needs to be imported as `@dynamic/xxx` by the users themselves.
+The difference is that the files generated by `enhanceAppFiles` will be loaded and applied automatically when the application is initialized on the client-side, while the files generated by `clientDynamicModules` need to be imported as `@dynamic/xxx` by the users themselves.
 
 ```js
 module.exports = (options, ctx) => ({
@@ -48,12 +48,12 @@ module.exports = (options, ctx) => ({
 
 ## When do I need to use `enhanceAppFiles`?
 
-1. I want to execute some code on the client side automatically.
-2. I don't have a need for reuse of this module.
+1. I want to execute some code on the client-side automatically.
+2. I don’t need to reuse this module.
 
 **Example:**
 
-- [@vuepress/plugin-register-components](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/plugin-register-components/index.js#L24): Automatically registering components on the client side.
+- [@vuepress/plugin-register-components](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/plugin-register-components/index.js#L24): Automatically registering components on the client-side.
 - [@vuepress/plugin-pagination](https://github.com/vuejs/vuepress/blob/master/packages/@vuepress/plugin-pagination/index.js#L14): Automatically insert Vue plugins to expand the API of the client.
 
 ## When do I need to use `clientDynamicModules`?
@@ -63,5 +63,5 @@ module.exports = (options, ctx) => ({
 
 **Example:**
 
-- [@vuepress/plugin-blog](https://github.com/ulivz/vuepress-plugin-blog/blob/master/src/index.ts#L167): Using compile-time metadata to generate some dynamic blog-related modules and initialize them on the client side by using `enhanceAppFiles`.
+- [@vuepress/plugin-blog](https://github.com/ulivz/vuepress-plugin-blog/blob/master/src/index.ts#L167): Using compile-time metadata to generate some dynamic blog-related modules and initialize them on the client-side by using `enhanceAppFiles`.