docs: polish doc

fi3ework · Jan 25, 2023 · 8c0f9fd · 8c0f9fd
1 parent fee7924
commit 8c0f9fd
Show file tree

Hide file tree

Showing 11 changed files with 64 additions and 54 deletions.
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -40,8 +40,8 @@ function sidebar() {
         { text: 'TypeScript', link: '/checkers/typescript' },
         { text: 'vue-tsc', link: '/checkers/vue-tsc' },
         { text: 'ESLint', link: '/checkers/eslint' },
-        { text: 'VLS', link: '/checkers/vls' },
         { text: 'Stylelint', link: '/checkers/stylelint' },
+        { text: 'VLS', link: '/checkers/vls' },
       ],
     },
     {
@@ -52,7 +52,7 @@ function sidebar() {
     {
       text: 'FAQs',
       collapsible: true,
-      items: [{ text: 'Troubleshooting ', link: '/faq/troubleshooting' }],
+      items: [{ text: 'Integration', link: '/faq/integration' }],
     },
   ]
 }
diff --git a/docs/checkers/eslint.md b/docs/checkers/eslint.md
@@ -4,14 +4,15 @@
 
 1. Make sure [eslint](https://www.npmjs.com/package/eslint) and related plugins for your `eslintrc` are installed as peer dependencies.
 
-::: warning
-**(Optional but highly recommended)** Install `optionator@^0.9.1` with your package manager. It's needed because of ESLint dependents on it. It's probably working fine even it's not installed as it's accessed as a phantom dependency. But when you set `hoist=false` of pnpm. It won't be accessible anymore without explicit installation.
-
-:::
+   ::: warning
+   **(Optional but highly recommended)** Install `optionator@^0.9.1` with your package manager. It's needed because of ESLint dependents on it. It's probably working fine even it's not installed as it's accessed as a phantom dependency. But when you set `hoist=false` of pnpm. It won't be accessible anymore without explicit installation.
+   :::
 
 2. Add `eslint` field to plugin config and `options.eslint.lintCommand` is required. The `lintCommand` is the same as the lint command of your project. The default root of the command uses Vite's [root](https://vitejs.dev/config/#root).
 
+   :::tip
    Do not add `--fix` to the lint command since the plugin is only aiming at check issues.
+   :::
 
    ```js
    // e.g.

diff --git a/docs/checkers/overview.md b/docs/checkers/overview.md
@@ -1,10 +1,11 @@
 # Checkers overview
 
-vite-plugin-checkers provide built-in checkers. For now, it provides [TypeScript](/checkers/typescript), [ESLint](/checkers/eslint), [vue-tsc](/checkers/vue-tsc), [VLS](/checkers/vls), [Stylelint](/checkers/stylelint).
+vite-plugin-checkers provide built-in checkers. For now, it supports [TypeScript](/checkers/typescript), [ESLint](/checkers/eslint), [vue-tsc](/checkers/vue-tsc), [VLS](/checkers/vls), [Stylelint](/checkers/stylelint).
 
 ## How to add a checker
 
-- Set to `true` to use a checker with its default value (except ESLint and Stylelint).
-- Leave the field blank or `false` to disable the checker.
-- Make sure to install the peer dependencies indicated of each checker.
+- Set the checker property to `true` to use a checker with its default value (except ESLint and Stylelint).
+- Leave the field blank or `false` will not use the checker.
+- Make sure to install the peer dependencies that checker relies on (documented on each checker's page if needed).
 - Checker can be enabled with an advanced object config.
+- Use [config](/configuration/config) to control the common behaviors settings of checkers.
diff --git a/docs/checkers/stylelint.md b/docs/checkers/stylelint.md
@@ -4,14 +4,15 @@
 
 1. Make sure [stylelint](https://www.npmjs.com/package/stylelint) and related plugins for your `stylelintrc` are installed as peer dependencies.
 
-::: warning
-**(Optional but highly recommended)** Install `meow@^9.0.0` with your package manager. It's needed because of Stylelint dependents on it. It's probably working fine even it's not installed as it's accessed as a phantom dependency. But when you set `hoist=false` of pnpm. It won't be accessible anymore without explicit installation.
-
-:::
+   ::: warning
+   **(Optional but highly recommended)** Install `meow@^9.0.0` with your package manager. It's needed because of Stylelint dependents on it. It's probably working fine even it's not installed as it's accessed as a phantom dependency. But when you set `hoist=false` of pnpm. It won't be accessible anymore without explicit installation.\
+   :::
 
 2. Add `stylelint` field to plugin config and `options.stylelint.lintCommand` is required. The `lintCommand` is the same as the lint command of your project. The default root of the command uses Vite's [root](https://vitejs.dev/config/#root).
 
+   :::tip
    Do not add `--fix` to the lint command since the plugin is only aiming at check issues.
+   :::
 
    ```js
    // e.g.

diff --git a/docs/checkers/typescript.md b/docs/checkers/typescript.md
@@ -8,11 +8,11 @@ You can use TypeScript checker for vanilla TypeScript project or React project.
 
 2. Add `typescript` field to plugin config.
 
-```js
-export default {
-  plugins: [checker({ typescript: true /** or an object config */ })],
-}
-```
+   ```js
+   export default {
+     plugins: [checker({ typescript: true /** or an object config */ })],
+   }
+   ```
 
 ## Configuration
 

diff --git a/docs/checkers/vls.md b/docs/checkers/vls.md
@@ -30,16 +30,21 @@ See [`initParams.ts`](https://github.com/fi3ework/vite-plugin-checker/blob/8fc5d
 For example, to performing checking only the `<script>` block:
 
 ```ts
-checker({
-  vls: {
-    vetur: {
-      validation: {
-        template: false,
-        templateProps: false,
-        interpolation: false,
-        style: false,
+// e.g.
+export default {
+  plugins: [
+    checker({
+      vls: {
+        vetur: {
+          validation: {
+            template: false,
+            templateProps: false,
+            interpolation: false,
+            style: false,
+          },
+        },
       },
-    },
-  },
-}),
+    }),
+  ],
+}
 ```
diff --git a/docs/checkers/vue-tsc.md b/docs/checkers/vue-tsc.md
@@ -6,21 +6,21 @@ You can use vue-tsc checker for your Vue3 project. If you're still using Vue2, c
 
 1. Make sure [vue-tsc](https://www.npmjs.com/package/vue-tsc) & [typescript](https://www.npmjs.com/package/typescript) are installed as a peer dependency of your Vite project.
 
-```bash
-pnpm add vue-tsc@latest typescript -D
-```
+   ```bash
+   pnpm add vue-tsc@latest typescript -D
+   ```
 
-::: warning
-The `vue-tsc` version **must** >= `0.33.9`.
-:::
+   ::: tip
+   The `vue-tsc` version **must** >= `0.33.9`. `vue-tsc` has released `1.0.0` version, it's recommended to try it out.
+   :::
 
 2. Add `vueTsc` field to plugin config.
 
-```js
-export default {
-  plugins: [checker({ vueTsc: true /** or an object config */ })],
-}
-```
+   ```js
+   export default {
+     plugins: [checker({ vueTsc: true /** or an object config */ })],
+   }
+   ```
 
 ## Configuration
 
@@ -31,4 +31,4 @@ Advanced object configuration table of `options.vueTsc`
 | root         | `string` | [Vite config](https://vitejs.dev/config/#root) `root` | Root path to find tsconfig file  |
 | tsconfigPath | `string` | `"tsconfig.json"`                                     | Relative tsconfig path to `root` |
 
-3. (Optional for Vue2 user) The type check is powered by `vue-tsc` so it supports Vue2 according to the [documentation](https://github.com/johnsoncodehk/volar#using), you need to install `@vue/runtime-dom` by yourself.
+3. **(optional for Vue2 project only)** The type check is powered by `vue-tsc` so it supports Vue2 according to the [documentation](https://github.com/johnsoncodehk/volar#using), you need to install `@vue/runtime-dom` by yourself.
diff --git a/docs/configuration/config.md b/docs/configuration/config.md
@@ -1,6 +1,6 @@
 # Configurations
 
-Shared configuration to control the behaviors of the plugin.
+Shared configuration to control the checker behaviors of the plugin.
 
 ```ts
 {

diff --git a/docs/faq/troubleshooting.md → docs/faq/integration.md b/docs/faq/troubleshooting.md → docs/faq/integration.md
@@ -1,9 +1,6 @@
-# Troubleshooting
+# Integration
 
-This section lists a few common gotchas, and bugs introduced in the past.
-Please skim through before [opening an issue](https://github.com/fi3ework/vite-plugin-checker/issues/new/choose).
-
-## HMR Issues
+## with traditional backend
 
 ### Hot Module Refresh does not work when integrating with backend
 

diff --git a/docs/introduction/getting-started.md b/docs/introduction/getting-started.md
@@ -1,6 +1,6 @@
 # Getting Started
 
-1. Install plugin (pnpm recommended).
+1. Install plugin (pnpm recommended 🚀).
 
    ```bash
    pnpm add vite-plugin-checker -D
@@ -13,13 +13,18 @@
    npm i vite-plugin-checker -D
    ```
 
-2. Add plugin to Vite config file. Add the checker you need. We add TypeScript below as an example. See all available checkers [here](/checkers/overview).
+2. Add plugin to Vite config file and config the checker you need. We add TypeScript here as an example. See all available checkers [here](/checkers/overview).
 
    ```ts
    // vite.config.js
    import checker from 'vite-plugin-checker'
    export default {
-     plugins: [checker({ typescript: true })], // e.g. use TypeScript check
+     plugins: [
+       checker({
+         // e.g. use TypeScript check
+         typescript: true,
+       }),
+     ],
    }
    ```
 
@@ -43,5 +48,5 @@ It's recommended to open a browser for a better terminal flush, see [#27](https:
 :::
 
 ::: warning
-`server.ws.on` is introduced to Vite in [2.6.8](https://github.com/vitejs/vite/blob/main/packages/vite/CHANGELOG.md#268-2021-10-18). vite-plugin-checker relies on `server.ws.on` to bring diagnostics back after a full reload and it' not available for older version of Vite.
+`server.ws.on` is introduced to Vite in [2.6.8](https://github.com/vitejs/vite/blob/main/packages/vite/CHANGELOG.md#268-2021-10-18). vite-plugin-checker relies on `server.ws.on` to make overlay visible after opening a new browser tab.
 :::
diff --git a/docs/introduction/introduction.md b/docs/introduction/introduction.md
@@ -1,6 +1,6 @@
 # About vite-plugin-checker
 
-A Vite plugin that can run TypeScript, VLS, vue-tsc, ESLint, Stylelint in worker thread.
+A Vite plugin that can run TypeScript, VLS, vue-tsc, ESLint, Stylelint in worker thread to **add type checking and linting support** for Vite.
 
 <div :style="{ 'display': 'flex' }">
   <a href="https://www.npmjs.com/package/vite-plugin-checker" :style="{ 'margin-right': '4px' }"><img src="https://img.shields.io/npm/v/vite-plugin-checker" /></a>
@@ -13,7 +13,7 @@ A Vite plugin that can run TypeScript, VLS, vue-tsc, ESLint, Stylelint in worker
   <img alt="screenshot" src="https://user-images.githubusercontent.com/12322740/152739742-7444ee62-9ca7-4379-8f02-495c612ecc5c.png">
 </p>
 
-> History version documentations [0.1](https://github.com/fi3ework/vite-plugin-checker/tree/v0.1.x), [0.2](https://github.com/fi3ework/vite-plugin-checker/tree/v0.2), [0.3](https://github.com/fi3ework/vite-plugin-checker/tree/v0.3.x), [0.4](https://github.com/fi3ework/vite-plugin-checker/tree/v0.4.x/docs). It's highly recommended to use latest version before 1.0.0, although there's some breaking changes, the plugin configuration is quite simple.
+> History version documentations [0.1](https://github.com/fi3ework/vite-plugin-checker/tree/v0.1.x), [0.2](https://github.com/fi3ework/vite-plugin-checker/tree/v0.2), [0.3](https://github.com/fi3ework/vite-plugin-checker/tree/v0.3.x), [0.4](https://github.com/fi3ework/vite-plugin-checker/tree/v0.4.x/docs). It's highly recommended to use latest version before 1.0.0, although there's some breaking changes in each version bumping, the plugin configuration is quite simple.
 
 ## Online playground