Add support for Desktop device, other languages, and some other clarity tidying (#477)

* Generalize intro beyond Lighthouse report

* Not sure what "Usage" means exactly so ✂️ it

* Improve visibility & rationales for installation options

Add new structure here with links to new sections

* Adding the 2 options at the top of this section

* UI installation recap

* Verbify headers

* Move example to its own section

* Add draft versions of new sections

* Refine language examples

* More refinements

* Some reframing

* Standardize headers and order

* minor qualification for file-based installation

* Remove "build" here to reduce nouns and cognitive processing load for newer users

* Apply suggestions from code review

Co-authored-by: Jack Brewer <[email protected]>

* Apply Jack's input to add locale l"ist"

* Apply header reframe here

Co-authored-by: Nasiba Carrasco Lanchas <[email protected]>

* Apply suggestions from code review

* Remove multi-site-path support

* Add general line about config options

* Revise desktop device section

* Revise locale section

Co-authored-by: Jack Brewer <[email protected]>
Co-authored-by: Nasiba Carrasco Lanchas <[email protected]>

Author: 3 people

README.md

@@ -2,17 +2,24 @@
 
 A Netlify plugin to generate a Lighthouse report for every deploy
 
-## Usage
+## Installation options
 
-If you would like to run the Lighthouse build plugin for multiple site paths, such as for the site root path and a contact page, we recommend installing the build plugin manually in the `netlify.toml` file.
+You can install the plugin for your site using your `netlify.toml` file or the Netlify UI. 
+
+For the most customization options, we recommend installing the Lighthouse plugin with a `netlify.toml` file.
+
+`netlify.toml` file-based installation allows you to:
+  - [Run Lighthouse audits for different site paths, such as the contact page and site home page](#run-lighthouse-for-different-site-paths)
+  - [Run Lighthouse audits for a desktop device](#run-lighthouse-for-the-desktop-experience)
+  - [Generate Lighthouse results in a language other than English](#generate-lighthouse-results-in-other-languages)
 
 ### Install plugin through the Netlify UI
 
-You can install this plugin in the Netlify UI from this [direct in-app installation link](https://app.netlify.com/plugins/@netlify/plugin-lighthouse/install) or from the [Plugins directory](https://app.netlify.com/plugins).
+For UI-based installation, you can install this plugin from the [Integrations Hub](https://www.netlify.com/integrations/lighthouse/), the [Plugins directory](https://app.netlify.com/plugins), or through this [direct installation link](https://app.netlify.com/plugins/@netlify/plugin-lighthouse/install).
 
-### Install plugin through the `netlify.toml` file
+### Install plugin with a `netlify.toml` file
 
-You can also install it manually:
+To install the plugin manually:
 
 From your project's base directory, use npm, yarn, or any other Node.js package manager to add the plugin to `devDependencies` in `package.json`.
 
@@ -66,23 +73,7 @@ You can customize the behavior via the `audits` input:
       performance = 0.8
 ```
 
-Example `netlify.toml` file that audits the site root path and a contact page:
-
-```
-[[plugins]]
-  package = "@netlify/plugin-lighthouse"
-
-  # Generate a Lighthouse report for the site's root path
-  [[plugins.inputs.audits]]
-  path = ""
-
-  # Generate a Lighthouse report for the contact site path
-  [[plugins.inputs.audits]]
-  path = "contact"
-
-```
-
-The Lighthouse report results are automatically printed to the **Deploy log** in the Netlify UI. For example:
+The lighthouse scores are automatically printed to the **Deploy log** in the Netlify UI. For example:
 
 ```
 2:35:07 PM: ────────────────────────────────────────────────────────────────
@@ -104,18 +95,45 @@ The Lighthouse report results are automatically printed to the **Deploy log** in
 2:35:17 PM: }
 ```
 
-We currently support the following settings, which are passed directly to Lighthouse:
+## Lighthouse plugin configuration options
+
+To customize how Lighthouse runs audits, you can make changes to the `netlify.toml` file.
+
+### Run Lighthouse audits for desktop
+
+By default, Lighthouse takes a mobile-first performance testing approach and runs audits for the mobile device experience. You can optionally run Lighthouse audits for the desktop experience by including `preset = "desktop"` in your `netlify.toml` file:
 
 ```
 [[plugins]]
   package = "@netlify/plugin-lighthouse"
 
   [plugins.inputs.settings]
     preset = "desktop" # Optionally run Lighthouse using a desktop configuration
-    locale = "es" # Any Lighthouse-supported locale, used to generate reports in a different language
 ```
 
-## Running Locally
+Updates to `netlify.toml` will take effect for new builds.
+
+To return to running Lighthouse audits for the mobile experience, just remove the line `preset = "desktop"`. New builds will run Lighthouse for the mobile experience.
+
+### Generate Lighthouse results in other languages
+
+By default, Lighthouse results are generated in English. To return Lighthouse results in other languages, include the language code from any Lighthouse-supported locale in your `netlify.toml` file. 
+
+For the latest Lighthouse supported locales or language codes, check out this [official Lighthouse code](https://github.com/GoogleChrome/lighthouse/blob/da3c865d698abc9365fa7bb087a08ce8c89b0a05/types/lhr/settings.d.ts#L9).
+
+Updates to `netlify.toml` will take effect for new builds.
+
+#### Example to generate Lighthouse results in Spanish
+
+```
+[[plugins]]
+  package = "@netlify/plugin-lighthouse"
+
+  [plugins.inputs.settings]
+    locale = "es" # generates Lighthouse reports in Español
+```
+
+### Run Lighthouse Locally
 
 Fork and clone this repo.
 
@@ -126,9 +144,11 @@ yarn install
 yarn local
 ```
 
-## Lighthouse Score Visualizations (Labs feature)
+## Preview Lighthouse results within the Netlify UI
+
+Netlify offers an experimental feature through Netlify Labs that allows you to view Lighthouse scores for each of your builds on your site's Deploy Details page with a much richer format. 
 
-When you install the [Lighthouse Build Plugin](https://app.netlify.com/plugins/@netlify/plugin-lighthouse/install) on your site and enable this experimental feature, you can view the Lighthouse scores for each of your builds on your site's Deploy Details page with a much richer format.
+You'll need to install the [Lighthouse build plugin](https://app.netlify.com/plugins/@netlify/plugin-lighthouse/install) on your site and then enable this experimental feature through Netlify Labs.
 
 <img width="1400" alt="Deploy view with Lighthouse visualizations" src="https://user-images.githubusercontent.com/79875905/160019039-c3e529de-f389-42bc-a3d4-458c90d59e6a.png">