docs: Clearify the browser startup guide (#110)

Author: aklinker1

docs/config/plugin-options.md

@@ -1,11 +1,9 @@
 ---
 lang: en-US
-title: Plugin Options
+title: Plugin Configuration Options
 ---
 
-# Plugin Options
-
-These options are available when adding the plugin in your `vite.config.ts`
+# Plugin Configuration Options
 
 ```ts
 import { defineConfig } from "vite";
@@ -26,15 +24,15 @@ export default defineConfig({
 additionalInputs?: string[]
 ```
 
-A list of paths relative to Vite's root directory that should be built along with the inputs listed in your manifest.
+An array of paths relative to Vite's root directory that should be built along with the inputs listed in your manifest.
 
-Usually, this is additional HTML files that aren't listed in your manifest, but still want to show, like an onboarding page. It also accepts stylesheets (CSS, SCSS, Stylus, etc) and scripts (JS or TS), essentially everything that Vite knows how to build.
+This generally involves additional HTML files not listed in your manifest but which you still want to display, such as an onboarding page. It also accepts stylesheets (CSS, SCSS, Stylus, etc.) and scripts (JS or TS) - basically, anything that Vite can build.
 
-Depending on the type of file listed, it will be built at different times:
+Depending on the type of file provided, it will be built at different stages:
 
-- HTML files are built in the same step along side the other HTML files listed in the manifest.
-- JS files are bundled individually in the order listed.
-- CSS files are also bundled individually in the order listed.
+- HTML files are built in the same step alongside the other HTML files listed in the manifest.
+- JS files are bundled individually in the order specified.
+- CSS files are also bundled individually in the order given.
 
 ## `browser`
 
@@ -46,30 +44,30 @@ browser?: string
 const browser = "{{browser}}"
 </script>
 
-When using <code>{{browser}}.</code> prefixes in your manifest template, setting this field will cause only the matching tags to be in the `<outDir>/manifest.json`.
+When using <code>{{browser}}.</code> prefixes in your manifest template, defining this field ensures that only matching tags are included in the `<outDir>/manifest.json`.
 
-See [Supporting Multiple Browsers](/guide/supporting-multiple-browsers) to learn more about how to use the `browser` option in combination with manifest templates.
+Refer to [Multibrowser Support](/guide/supporting-multiple-browsers) for more details on how to use this option with manifest templates.
 
 ## `disableAutoLaunch`
 
 ```ts
 disableAutoLaunch?: boolean;
 ```
 
-Setting to `true` will prevent the browser from opening when starting the dev server or running the extension in watch mode.
+Setting this to `true` prevents the browser from launching when starting the development server or running the extension in watch mode.
 
-This can be useful in setups where opening the browser is impossible, like in the WSL/WSL2. In this case, the linux shell can't communicate with the Window's browser, and it crashes. Setting `disableAutoLaunch: true` will trigger rebuild's when you save a file, and you can open an install the extension manually.
+This is useful in setups where opening the browser isn't possible, such as in WSL/WSL2. In these scenarios, the Linux shell can't communicate with the Windows browser, leading to crashes. Setting `disableAutoLaunch: true` will trigger rebuilds when you save a file, and you can manually open and install the extension.
 
 ## `htmlViteConfig`
 
 ```ts
 htmlViteConfig?: import('vite').InlineConfig
 ```
 
-You can provide additional Vite config to the HTML multipage build step by setting it here.
+You can supply additional Vite configuration to the HTML multipage build step here.
 
 ::: warning
-Use with caution, I have not tested the compatibility of every single Vite build option with the HTML build process. Submit an issue if you have any problems.
+Exercise caution with this option. Not every one of Vite's build options have been tested for compatibility. If something doesn't work for you, please open an issue.
 :::
 
 ## `manifest`
@@ -78,33 +76,34 @@ Use with caution, I have not tested the compatibility of every single Vite build
 manifest?: string | (() => any) | (() => Promise<any>)
 ```
 
-The manifest can either be:
+The manifest can be:
 
-- The path relative to Vite's root directory to a file containing a manifest template
-- A function that returns the manifest template as a JSON object.
+- A path relative to Vite's root directory pointing to a file containing a manifest template.
+- An absolute path pointing to a file containing a manifest template.
+- A function returning the manifest template as a JSON object.
 
-When not provided, it defaults to `"manifest.json"`, and the plugin looks for a template at `<viteRoot>/manifest.json`.
+When not provided, it defaults to `"manifest.json"`, and the plugin searches for a template at `<viteRoot>/manifest.json`.
 
-See [Supporting Multiple Browsers](/guide/supporting-multiple-browsers) to learn more about how to use manifest templates.
+Refer to [Multibrowser Support](/guide/supporting-multiple-browsers) for more information on how to use manifest templates.
 
 ## `printSummary`
 
 ```ts
 printSummary?: boolean
 ```
 
-Defaults to `true`. When `true`, the plugin will print a summary of what files are being built in what order.
+Defaults to `true`. When set to `true`, the plugin will provide a summary of what files are being built and in what order.
 
 ## `scriptViteConfig`
 
 ```ts
 scriptViteConfig?: import('vite').InlineConfig
 ```
 
-You can provide additional Vite config to the individually bundled JS files by setting it here.
+You can provide additional Vite config to individually bundled JS files here.
 
 ::: warning
-Use with caution, I have not tested the compatibility of every single Vite build option with the HTML build process. Submit an issue if you have any problems.
+Exercise caution with this option. Not every one of Vite's build options have been tested for compatibility. If something doesn't work for you, please open an issue.
 :::
 
 ## `skipManifestValidation`
@@ -113,30 +112,26 @@ Use with caution, I have not tested the compatibility of every single Vite build
 skipManifestValidation?: boolean
 ```
 
-By default, the `<outDir>/manifest.json` will be validated against Google's JSON schema: <https://json.schemastore.org/chrome-manifest>.
+By default, the `<outDir>/manifest.json` undergoes validation against Google's JSON schema at <https://json.schemastore.org/chrome-manifest>.
 
-Setting this to `true` will skip validation.
+Setting this to `true` skips the validation step.
 
-> The validation process downloads the schema from the above URL. If you are working offline, this step will be skipped automatically.
+> The validation process downloads the schema from the given URL. If you are working offline, this step will automatically be skipped.
 
 ## `watchFilePaths`
 
 ```ts
 watchFilePaths?: string[]
 ```
 
-A list of paths relative to Vite's root directory that cause a full rebuild of the extension during development. When one of these files is saved, the browser will be shut down, manifest regenerated, and the browser will open again.
+An array of paths relative to Vite's root directory that triggers a complete rebuild of the extension during development. When one of these files is saved, the browser will be closed, the manifest regenerated, and the browser will relaunch.
 
-If the `manifest` field was a string, it will be added to this list automatically. If the `manifest` field is a function, you should add any files that are used to generate the manifest (like `package.json`).
+If the [`manifest` field](#manifest) was a string, it will be automatically added to this list. If the [`manifest` field](#manifest) is a function, you should add any files used to generate the manifest (like package.json).
 
 ## `webExtConfig`
 
 ```ts
 webExtConfig?: any
 ```
 
-Configure the startup behavior of the browser.
-
-See [`web-ext`'s source code](https://github.com/mozilla/web-ext/blob/666886f40a967b515d43cf38fc9aec67ad744d89/src/program.js#L559) for possible options.
-
-See [Configure Browser Startup](/guide/configure-browser-startup.md) for alteratives and more details on how this field is used.
+This option allows you to pass configuration into `web-ext` when launching the browser. For more details, refer to [Browser Startup Configuration](/guide/configure-browser-startup.md).

docs/guide/building-for-production.md

@@ -1,26 +1,30 @@
 ---
 lang: en-US
-title: Building for Production
+title: Generating a Production Build
 ---
 
-# Building for Production
+# Generating a Production Build
 
-## Overview
+## Introduction
 
-Like with a regular Vite project, just run the build command:
+Creating a production build with Vite is as straightforward as running the build command, just like you would with a standard Vite project:
 
 ```bash
 vite build
 ```
 
-Then look in your `dist/` directory. You should find a fully functioning browser extension! You can load it into Chrome or Firefox as an unpacked extension.
+After running the above command, go to your `dist/` directory. There, you'll find a fully functional web extension! You can proceed to load this extension into Chrome or Firefox as an unpacked extension for testing.
 
-## Zipping
+## Uploading to a Store
 
-To publish your extension to the store, you simply need to zip up the files inside your output directory. You can do this manually, or use a package like [`zip-a-folder`](https://www.npmjs.com/package/zip-a-folder) to automate it.
+When you're ready to publish your extension to the store, you'll need to zip up the files contained in your output directory. This can be done manually or automated with a package such as [`zip-a-folder`](https://www.npmjs.com/package/zip-a-folder).
 
-```ts
-import { zip } from "zip-a-folder";
-
-await zip("dist", "extension.zip");
-```
+> The following is an example of how to use `zip-a-folder`:
+>
+> ```ts
+> import { zip } from "zip-a-folder";
+>
+> await zip("dist", "extension.zip");
+> ```
+>
+> This script will zip the contents of the `dist` directory and save it as `extension.zip`.

docs/guide/configure-browser-startup.md

@@ -1,20 +1,22 @@
 ---
 lang: en-US
-title: Configure Browser Startup
+title: Browser Startup Configuration
 ---
 
-# Configure Browser Startup
+# Browser Startup Configuration
 
-Internally, `vite-plugin-web-extension` uses [`web-ext`](https://www.npmjs.com/package/web-ext) by Mozilla to open the browser and install the extension during development. It can open any Chromium-based browser (Chrome, Edge, etc) and Firefox.
+## Overview
 
-You can configure it's startup behavior in two ways:
+Internally, `vite-plugin-web-extension` uses the JS API provided by [`web-ext`](https://www.npmjs.com/package/web-ext) to launch the browser and install the extension during development. It's capable of opening any Chromium-based browser (such as Chrome or Edge) and Firefox.
 
-1. Pass [`webExtConfig`](/config/plugin-options#webextconfig) option into the plugin
-2. Use config files
+There are two approaches to configure browser startup:
 
-## Pass `webExtConfig`
+1. Using the [`webExtConfig`](/config/plugin-options#webextconfig) option within the plugin
+2. Creating config files
 
-This is a good option if you're OK with checking the config into version control (since you will have to list the config in `vite.config.ts`), or if you need to set something based on a runtime value, like an environment variable.
+## The `webExtConfig` Option
+
+This method is ideal for config that needs to be committed to version control (as it will be defined in `vite.config.ts`), or if a configuration based on a runtime value, like an environment variable, is required.
 
 ```ts
 import { defineConfig } from "vite";
@@ -25,18 +27,18 @@ export default defineConfig({
     webExtension({
       // ...
       webExtConfig: {
-        startUrl: ["https://google.com"],
+        startUrl: process.env.START_URL.split(","),
       },
     }),
   ],
 });
 ```
 
-## Use Config Files
+## Config Files
 
-The plugin will automatically discover config files on your filesystem. Below are the paths that the plugin will look for config files at. When multiple files are found, they are merged into a single config.
+The plugin will automatically discover config files on your filesystem. The plugin searches for config files at the paths listed below. When multiple files are found, they are merged into a single configuration.
 
-The higher priority files (top of this list) are will override fields set by the lower priority files (bottom of the list).
+Higher priority files (top of the list) will override fields set by lower priority files (bottom of the list).
 
 1. `webExtConfig` option
 1. `<viteRoot>/.webextrc`
@@ -46,9 +48,9 @@ The higher priority files (top of this list) are will override fields set by the
 1. `~/.webextrc`
 1. `~/.webextrc.(json|json5|yml|yaml)`
 
-> Array fields are overwritten, not combined in any way.
+> Array fields are overwritten, they are not combined.
 
-Here's an example: You prefer to use Chrome Beta and Firefox Developer Edition, so you want one of those to open during development. You can create a `.webextrc` file in your home directory, and any project that uses `vite-plugin-web-extension` will know to use those versions instead of the default versions!
+Here's an example: Suppose you prefer to use Chrome Beta and Firefox Developer Edition, and you want one of these to open during development. You can create a `.webextrc` file in your home directory, and any project using `vite-plugin-web-extension` will use those versions instead of the default ones!
 
 ```json
 // ~/.webextrc
@@ -57,3 +59,23 @@ Here's an example: You prefer to use Chrome Beta and Firefox Developer Edition,
   "firefox": "firefoxdeveloperedition"
 }
 ```
+
+## Available Options
+
+Refer to Mozilla's [`web-ext run` CLI reference](https://extensionworkshop.com/documentation/develop/web-ext-command-reference/#web-ext-run) for a complete list of available options.
+
+Just convert each `--kebab-case` flag to `camelCase` and include them in your configuration.
+
+For instance, if you want to use Microsoft Edge, use the default user profile, customize the starting URLs, and alter the initial window size, your config file would look like:
+
+<!-- prettier-ignore -->
+```yml
+# ./.webextrc.yml
+chromiumBinary: /absolute/path/to/edge            # from --chromium-binary
+chromiumProfile: /absolute/path/to/edge/profile   # from --chromium-profile
+startUrl:                                         # from --start-url
+  - https://google.com
+  - https://duckduckgo.com
+args:                                             # from --args
+  - --window-size=400x300
+```

docs/guide/development.md

@@ -1,42 +1,45 @@
 ---
 lang: en-US
-title: Development
+title: Development Cycle
 ---
 
-# Development Cycle
+# Understanding the Development Cycle
 
-You have two ways to run the extension during development:
+While developing your browser extension, there are two ways to run it:
 
-- Dev Mode
+- Development Mode
 - Watch Mode
 
-Both will automatically open a browser window and install the extension automatically.
+Both methods will automatically open a new browser window and install the extension for you.
 
 ::: info
-Dev mode is recommended because it will let you iterate faster as your project grows in size.
+For most use cases, Development Mode is recommended as it can significantly speed up the development process, especially as your project scales.
 :::
 
-## Dev Mode
+## Development Mode
+
+To start the extension in development mode, run the following command:
 
 ```sh
 vite dev
 ```
 
-Just run Vite like you would a normal project. This will spin up the dev server, and you'll have HMR for all the HTML pages in your extension!
+This command starts the Vite development server, similar to how you would for any other Vite project. Notably, you will have Hot Module Replacement (HMR) enabled for all HTML pages in your extension!
 
-Unfortunately, content scripts do not work with HMR. Instead, they are built using watch mode, see below. When you save a file used by a content script, it will cause the entire extension to reload once the file has finished building.
+However, please note that content scripts do not support HMR. They are built using [Watch Mode](#watch-mode), see below. Thus, when you modify and save a file associated with a content script, it will trigger a full reload of the extension once the file has finished building.
 
 ::: warning HMR requires Chrome v110 or above
-
-Make sure your browser is up to date, or it won't work. Chrome v110 was released Feb 13, 2023.
+Ensure your browser is up to date. HMR functionality is only supported in Chrome v110 or later versions, which was released on February 13, 2023.
 :::
 
 ## Watch Mode
 
+To start the extension in watch mode, run the following command:
+
 ```sh
 vite build --watch --mode development
 ```
 
-Rather than starting the dev server, using Vite's `--watch` flag will cause it to rebuild the extension when a file is saved.
+Instead of launching the development server, using the `--watch` flag with Vite will instruct it to rebuild the extension each time you save a file.
 
-If you can't use dev mode, watch mode will be easier than installing and reloading the extension by hand. Be aware that, as an extension grows larger, watch mode can get very slow since it's doing a full production build with minimal caching.
+If [Development Mode](#development-mode) does not work for you, Watch Mode can be a convenient alternative. However, be aware that as an extension grows in complexity, Watch Mode may become significantly slower as it completes a full production build with minimal caching, after each change.