docs: improve docs (#9179)

This PR drastically improves the documentation by improving the sidebars and adding a GitHub icon. Fixed: #9176 Fixed: #9173 ![image](https://user-images.githubusercontent.com/101637635/198374826-399219f6-e04f-4613-9613-f7e3281d332f.png)
puppeteer · Oct 28, 2022 · 2d2120c · 2d2120c
1 parent f3ff18e
commit 2d2120c
Show file tree

Hide file tree

Showing 26 changed files with 385 additions and 288 deletions.
diff --git a/.prettierrc.cjs b/.prettierrc.cjs
@@ -3,5 +3,5 @@
  */
 module.exports = {
   ...require('gts/.prettierrc.json'),
-  //   proseWrap: 'always', // Uncomment this while working on Markdown documents. MAKE SURE TO COMMENT THIS BEFORE RUNNING CHECKS/FORMATS OR EVERYTHING WILL BE MODIFIED.
+  // proseWrap: 'always', // Uncomment this while working on Markdown documents. MAKE SURE TO COMMENT THIS BEFORE RUNNING CHECKS/FORMATS OR EVERYTHING WILL BE MODIFIED.
 };
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 
 <img src="https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png" height="200" align="right"/>
 
-#### [Guides](https://pptr.dev/guides) | [API](https://pptr.dev/api) | [FAQ](https://pptr.dev/faq) | [Contributing](https://pptr.dev/contributing) | [Troubleshooting](https://pptr.dev/troubleshooting)
+#### [Guides](https://pptr.dev/category/guides) | [API](https://pptr.dev/api) | [FAQ](https://pptr.dev/faq) | [Contributing](https://pptr.dev/contributing) | [Troubleshooting](https://pptr.dev/troubleshooting)
 
 > Puppeteer is a Node.js library which provides a high-level API to control
 > Chrome/Chromium over the
@@ -49,7 +49,7 @@ Chromium (~170MB macOS, ~282MB Linux, ~280MB Windows) that is
 with Puppeteer. For a version of Puppeteer without installation, see
 [`puppeteer-core`](#puppeteer-core).
 
-#### Configuring Puppeteer
+#### Configuration
 
 Puppeteer uses several defaults that can be customized through configuration
 files.
@@ -73,8 +73,8 @@ module.exports = {
 After adding the configuration file, you will need to remove and reinstall
 `puppeteer` for it to take effect.
 
-See [Configuring
-Puppeteer](https://pptr.dev/guides/configuring-puppeteer) for more information.
+See the [configuration guide](https://pptr.dev/guides/configuration) for more
+information.
 
 #### `puppeteer-core`
 
@@ -85,21 +85,23 @@ Every release since v1.7.0 we publish two packages:
 
 `puppeteer` is a _product_ for browser automation. When installed, it downloads
 a version of Chromium, which it then drives using `puppeteer-core`. Being an
-end-user product, `puppeteer` automates several workflows using reasonable defaults [that can be customized](https://pptr.dev/guides/configuring-puppeteer).
+end-user product, `puppeteer` automates several workflows using reasonable
+defaults [that can be customized](https://pptr.dev/guides/configuration).
 
 `puppeteer-core` is a _library_ to help drive anything that supports DevTools
 protocol. Being a library, `puppeteer-core` is fully driven through its
 programmatic interface implying no defaults are assumed and `puppeteer-core`
 will not download Chromium when installed.
 
-You should use `puppeteer-core` if you are [connecting to a remote
-browser](https://pptr.dev/api/puppeteer.puppeteer.connect) or [managing browsers
-yourself](https://pptr.dev/api/puppeteer.browserfetcher). If you are managing
-browsers yourself, you will need to call
+You should use `puppeteer-core` if you are
+[connecting to a remote browser](https://pptr.dev/api/puppeteer.puppeteer.connect)
+or [managing browsers yourself](https://pptr.dev/api/puppeteer.browserfetcher).
+If you are managing browsers yourself, you will need to call
 [`puppeteer.launch`](https://pptr.dev/api/puppeteer.puppeteernode.launch) with
 an an explicit
 [`executablePath`](https://pptr.dev/api/puppeteer.launchoptions.executablepath)
-(or [`channel`](https://pptr.dev/api/puppeteer.launchoptions.channel) if it's installed in a standard location).
+(or [`channel`](https://pptr.dev/api/puppeteer.launchoptions.channel) if it's
+installed in a standard location).
 
 When using `puppeteer-core`, remember to change the import:
 
@@ -120,8 +122,8 @@ a [browser](https://pptr.dev/api/puppeteer.browser),
 [pages](https://pptr.dev/api/puppeteer.page), and then manipulate them with
 [Puppeteer's API](https://pptr.dev/api).
 
-For more in-depth usage, check our [guides](https://pptr.dev/guides) and
-[examples](https://github.com/puppeteer/puppeteer/tree/main/examples).
+For more in-depth usage, check our [guides](https://pptr.dev/category/guides)
+and [examples](https://github.com/puppeteer/puppeteer/tree/main/examples).
 
 #### Example
 
@@ -207,17 +209,16 @@ run**.
 
 #### Using Docker
 
-See our [guide on using Docker](https://pptr.dev/guides/docker).
+See our [Docker guide](https://pptr.dev/guides/docker).
 
 #### Using Chrome Extensions
 
-See our
-[guide on using Chrome extensions](https://pptr.dev/guides/chrome-extensions).
+See our [Chrome extensions guide](https://pptr.dev/guides/chrome-extensions).
 
 ## Resources
 
 - [API Documentation](https://pptr.dev/api)
-- [Guides](https://pptr.dev/guides)
+- [Guides](https://pptr.dev/category/guides)
 - [Examples](https://github.com/puppeteer/puppeteer/tree/main/examples)
 - [Community list of Puppeteer resources](https://github.com/transitive-bullshit/awesome-puppeteer)
 

diff --git a/docs/chromium-support.md b/docs/chromium-support.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 6
----
-
 # Chromium Support
 
 The following versions of Chromium are supported, mapped to Puppeteer version:

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 5
----
-
 # Contributing
 
 First of all, thank you for your interest in Puppeteer! We'd love to accept your
@@ -266,7 +262,8 @@ The following steps are needed to update the Chromium version.
    number.
 3. Update `versions.js` with the new Chromium-to-Puppeteer version mapping and
    update `lastMaintainedChromiumVersion` with the latest stable Chrome version.
-4. Run `npm run check`. If it fails, update `packages/puppeteer-core/package.json` and `packages/puppeteer/package.json`
+4. Run `npm run check`. If it fails, update
+   `packages/puppeteer-core/package.json` and `packages/puppeteer/package.json`
    with the expected `devtools-protocol` version.
 5. Run `npm run clean`, `npm run build` and `npm install`.
 6. Run `npm test` and ensure that all tests pass. If a test fails,

diff --git a/docs/faq.md b/docs/faq.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 3
----
-
 # FAQ
 
 ## Q: Who maintains Puppeteer?

diff --git a/docs/guides/_category_.yml b/docs/guides/_category_.yml
diff --git a/...n-19.2.0/guides/configuring-puppeteer.mdx → docs/guides/configuration.mdx b/...n-19.2.0/guides/configuring-puppeteer.mdx → docs/guides/configuration.mdx
@@ -1,4 +1,4 @@
-# Configuring Puppeteer
+# Configuration
 
 ```mdx-code-block
 import Tabs from '@theme/Tabs';
@@ -12,7 +12,8 @@ All defaults in Puppeteer can be customized in two ways:
 
 :::caution
 
-Note that some options are only customizable through environment variables (such as `HTTPS_PROXY`).
+Note that some options are only customizable through environment variables (such
+as `HTTPS_PROXY`).
 
 :::
 
@@ -32,8 +33,8 @@ Puppeteer will look up the file tree for any of the following formats:
 Puppeteer will also read a `puppeteer` key from your application's
 `package.json`.
 
-See the [`Configuration`](../api/puppeteer.configuration)
-interface for possible options.
+See the [`Configuration`](../api/puppeteer.configuration) interface for possible
+options.
 
 :::caution
 
@@ -116,10 +117,10 @@ experiments:
 
 ## Environment variables
 
-Along with configuration files, Puppeteer looks for certain [environment
-variables](https://en.wikipedia.org/wiki/Environment_variable) for customizing
-behavior. Environment variables will always override configuration file
-options when applicable.
+Along with configuration files, Puppeteer looks for certain
+[environment variables](https://en.wikipedia.org/wiki/Environment_variable) for
+customizing behavior. Environment variables will always override configuration
+file options when applicable.
 
 The following options are _environment-only_ options
 

diff --git a/docs/guides/debugging.md b/docs/guides/debugging.md
@@ -27,20 +27,20 @@ quick sanity check before diving into more complex methods.
 
 Sometimes it's useful to see what the browser is displaying. Instead of
 launching in
-[`headless`](../api/puppeteer.browserlaunchargumentoptions.headless)
-mode, launch a full version of the browser with
-[`headless`](../api/puppeteer.browserlaunchargumentoptions.headless)
-set to `false`:
+[`headless`](../api/puppeteer.browserlaunchargumentoptions.headless) mode,
+launch a full version of the browser with
+[`headless`](../api/puppeteer.browserlaunchargumentoptions.headless) set to
+`false`:
 
 ```ts
 const browser = await puppeteer.launch({headless: false});
 ```
 
 ### Puppeteer "slow-mo"
 
-The [`slowMo`](../api/puppeteer.browserconnectoptions.slowmo)
-option slows down Puppeteer operations by a specified amount of milliseconds.
-It's another way to help see what's going on.
+The [`slowMo`](../api/puppeteer.browserconnectoptions.slowmo) option slows down
+Puppeteer operations by a specified amount of milliseconds. It's another way to
+help see what's going on.
 
 ```ts
 const browser = await puppeteer.launch({
@@ -54,10 +54,9 @@ const browser = await puppeteer.launch({
 ### Capture `console.*` output
 
 Since client code runs in the browser, doing `console.*` in client code will not
-directly log to Node.js. However, you can
-[listen](../api/puppeteer.page.on) for the
-[`console`](../api/puppeteer.pageeventobject.console) event which
-returns a payload with the logged text.
+directly log to Node.js. However, you can [listen](../api/puppeteer.page.on) for
+the [`console`](../api/puppeteer.pageeventobject.console) event which returns a
+payload with the logged text.
 
 ```ts
 page.on('console', msg => console.log('PAGE LOG:', msg.text()));
@@ -67,9 +66,8 @@ await page.evaluate(() => console.log(`url is ${location.href}`));
 
 ### Use the debugger in the browser
 
-1. Set
-   [`devtools`](../api/puppeteer.browserlaunchargumentoptions.devtools)
-   to `true` when launching Puppeteer:
+1. Set [`devtools`](../api/puppeteer.browserlaunchargumentoptions.devtools) to
+   `true` when launching Puppeteer:
 
    ```ts
    const browser = await puppeteer.launch({devtools: true});
@@ -100,9 +98,8 @@ to this
 [Chromium bug](https://bugs.chromium.org/p/chromium/issues/detail?id=833928), so
 if you want to try something out, you have to add it to your test file.
 
-1. Set
-   [`headless`](../api/puppeteer.browserlaunchargumentoptions.headless)
-   to `false`.
+1. Set [`headless`](../api/puppeteer.browserlaunchargumentoptions.headless) to
+   `false`.
 2. Add `debugger` to any server code you want debugged. For example,
 
    ```ts

diff --git a/docs/index.md b/docs/index.md
@@ -1,15 +1,11 @@
----
-sidebar_position: 1
----
-
 # Puppeteer
 
 [![Build status](https://github.com/puppeteer/puppeteer/workflows/CI/badge.svg)](https://github.com/puppeteer/puppeteer/actions?query=workflow%3ACI)
 [![npm puppeteer package](https://img.shields.io/npm/v/puppeteer.svg)](https://npmjs.org/package/puppeteer)
 
 <img src="https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png" height="200" align="right"/>
 
-#### [Guides](https://pptr.dev/guides) | [API](https://pptr.dev/api) | [FAQ](https://pptr.dev/faq) | [Contributing](https://pptr.dev/contributing) | [Troubleshooting](https://pptr.dev/troubleshooting)
+#### [Guides](https://pptr.dev/category/guides) | [API](https://pptr.dev/api) | [FAQ](https://pptr.dev/faq) | [Contributing](https://pptr.dev/contributing) | [Troubleshooting](https://pptr.dev/troubleshooting)
 
 > Puppeteer is a Node.js library which provides a high-level API to control
 > Chrome/Chromium over the
@@ -53,7 +49,7 @@ Chromium (~170MB macOS, ~282MB Linux, ~280MB Windows) that is
 with Puppeteer. For a version of Puppeteer without installation, see
 [`puppeteer-core`](#puppeteer-core).
 
-#### Configuring Puppeteer
+#### Configuration
 
 Puppeteer uses several defaults that can be customized through configuration
 files.
@@ -77,8 +73,8 @@ module.exports = {
 After adding the configuration file, you will need to remove and reinstall
 `puppeteer` for it to take effect.
 
-See [Configuring
-Puppeteer](https://pptr.dev/guides/configuring-puppeteer) for more information.
+See [Configuring Puppeteer](https://pptr.dev/guides/configuration) for more
+information.
 
 #### `puppeteer-core`
 
@@ -89,21 +85,23 @@ Every release since v1.7.0 we publish two packages:
 
 `puppeteer` is a _product_ for browser automation. When installed, it downloads
 a version of Chromium, which it then drives using `puppeteer-core`. Being an
-end-user product, `puppeteer` automates several workflows using reasonable defaults [that can be customized](https://pptr.dev/guides/configuring-puppeteer).
+end-user product, `puppeteer` automates several workflows using reasonable
+defaults [that can be customized](https://pptr.dev/guides/configuration).
 
 `puppeteer-core` is a _library_ to help drive anything that supports DevTools
 protocol. Being a library, `puppeteer-core` is fully driven through its
 programmatic interface implying no defaults are assumed and `puppeteer-core`
 will not download Chromium when installed.
 
-You should use `puppeteer-core` if you are [connecting to a remote
-browser](https://pptr.dev/api/puppeteer.puppeteer.connect) or [managing browsers
-yourself](https://pptr.dev/api/puppeteer.browserfetcher). If you are managing
-browsers yourself, you will need to call
+You should use `puppeteer-core` if you are
+[connecting to a remote browser](https://pptr.dev/api/puppeteer.puppeteer.connect)
+or [managing browsers yourself](https://pptr.dev/api/puppeteer.browserfetcher).
+If you are managing browsers yourself, you will need to call
 [`puppeteer.launch`](https://pptr.dev/api/puppeteer.puppeteernode.launch) with
 an an explicit
 [`executablePath`](https://pptr.dev/api/puppeteer.launchoptions.executablepath)
-(or [`channel`](https://pptr.dev/api/puppeteer.launchoptions.channel) if it's installed in a standard location).
+(or [`channel`](https://pptr.dev/api/puppeteer.launchoptions.channel) if it's
+installed in a standard location).
 
 When using `puppeteer-core`, remember to change the import:
 
@@ -124,8 +122,8 @@ a [browser](https://pptr.dev/api/puppeteer.browser),
 [pages](https://pptr.dev/api/puppeteer.page), and then manipulate them with
 [Puppeteer's API](https://pptr.dev/api).
 
-For more in-depth usage, check our [guides](https://pptr.dev/guides) and
-[examples](https://github.com/puppeteer/puppeteer/tree/main/examples).
+For more in-depth usage, check our [guides](https://pptr.dev/category/guides)
+and [examples](https://github.com/puppeteer/puppeteer/tree/main/examples).
 
 #### Example
 
@@ -221,7 +219,7 @@ See our
 ## Resources
 
 - [API Documentation](https://pptr.dev/api)
-- [Guides](https://pptr.dev/guides)
+- [Guides](https://pptr.dev/category/guides)
 - [Examples](https://github.com/puppeteer/puppeteer/tree/main/examples)
 - [Community list of Puppeteer resources](https://github.com/transitive-bullshit/awesome-puppeteer)
 

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 4
----
-
 # Troubleshooting
 
 ## `Cannot find module 'puppeteer-core/internal/...'`
@@ -45,8 +41,8 @@ module.exports = {
 ```
 
 You will need to reinstall `puppeteer` in order for the configuration to take
-effect. See [Configuring
-Puppeteer](./guides/configuring-puppeteer) for more information.
+effect. See [Configuring Puppeteer](./guides/configuration) for more
+information.
 
 ## Chrome headless doesn't launch on Windows
 

diff --git a/tools/generate_docs.ts b/tools/generate_docs.ts
@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import {readFile, rm, writeFile} from 'fs/promises';
+import {copyFile, readFile, rm, writeFile} from 'fs/promises';
 import {join, resolve} from 'path';
 import {chdir} from 'process';
 import semver from 'semver';
@@ -51,13 +51,7 @@ function spliceIntoSection(
 
 (async () => {
   const job1 = job('', async ({inputs, outputs}) => {
-    const content = await readFile(inputs[0]!, 'utf-8');
-    const sectionContent = `
----
-sidebar_position: 1
----
-`;
-    await writeFile(outputs[0]!, sectionContent + content);
+    await copyFile(inputs[0]!, outputs[0]!);
   })
     .inputs(['README.md'])
     .outputs(['docs/index.md'])