github/puppeteer
0
0
Fork 0
mirror of https://github.com/puppeteer/puppeteer synced 2024-06-14 14:02:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: improve docs (#9179)

Browse Source 
This PR drastically improves the documentation by improving the sidebars
and adding a GitHub icon.

Fixed: https://github.com/puppeteer/puppeteer/pull/9176
Fixed: https://github.com/puppeteer/puppeteer/issues/9173


![image](https://user-images.githubusercontent.com/101637635/198374826-399219f6-e04f-4613-9613-f7e3281d332f.png)
This commit is contained in:
jrandolf 2022-10-28 08:49:28 +02:00 committed by GitHub
parent f3ff18e468
commit 2d2120cea1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
26 changed files with 386 additions and 289 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.prettierrc.cjs
View File

@ -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.
};

33
README.md
View File

@ -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)

4
docs/chromium-support.md
View File

@ -1,7 +1,3 @@
---
sidebar_position: 6
---
# Chromium Support
The following versions of Chromium are supported, mapped to Puppeteer version:

7
docs/contributing.md
View File

@ -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,

4
docs/faq.md
View File

@ -1,7 +1,3 @@
---
sidebar_position: 3
---
# FAQ
## Q: Who maintains Puppeteer?

6
docs/guides/_category_.yml
View File

@ -1,6 +0,0 @@
label: Guides
position: 2
collapsed: false
link:
type: generated-index
title: Puppeteer Guides

17
website/versioned_docs/version-19.2.0/guides/configuring-puppeteer.mdx → docs/guides/configuration.mdx
View File

@ -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

31
docs/guides/debugging.md
View File

@ -27,10 +27,10 @@ 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});
@ -38,9 +38,9 @@ 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

32
docs/index.md
View File

@ -1,7 +1,3 @@
---
sidebar_position: 1
---
# Puppeteer
[![Build status](https://github.com/puppeteer/puppeteer/workflows/CI/badge.svg)](https://github.com/puppeteer/puppeteer/actions?query=workflow%3ACI)
@ -9,7 +5,7 @@ sidebar_position: 1
<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)

8
docs/troubleshooting.md
View File

@ -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

10
tools/generate_docs.ts
View File

@ -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'])

273
website/docusaurus.config.js
View File

@ -21,6 +21,7 @@ const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');
const archivedVersions = require('./versionsArchived.json');
const assert = require('assert');
const DOC_ROUTE_BASE_PATH = '/';
const DOC_PATH = '../docs';
@ -59,6 +60,20 @@ const config = {
};
},
},
plugins: [
[
'client-redirects',
/** @type {import('@docusaurus/plugin-client-redirects').Options} */
({
redirects: [
{
from: '/guides',
to: '/category/guides',
},
],
}),
],
],
presets: [
[
'classic',
@ -69,110 +84,107 @@ const config = {
docs: {
async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) {
const sidebarItems = await defaultSidebarItemsGenerator(args);
const apiCategoryItem = sidebarItems.find(value => {
return value.type === 'category' && value.label === 'API';
const apiItem = sidebarItems.find(value => {
return value.type === 'doc' && value.label === 'API';
});
if (apiCategoryItem) {
/** @type {typeof sidebarItems} */
const newItems = [];
const categories = new Map();
for (const item of apiCategoryItem.items) {
const [namespace] = item.label.split('.');
if (!categories.has(namespace)) {
categories.set(namespace, [item]);
} else {
categories.get(namespace).push(item);
}
}
if (!apiItem) {
return sidebarItems;
}
const order = [
// PuppeteerNode and Puppeteer go first as the entrypoints into
// the Puppeteer API.
'PuppeteerNode',
'Puppeteer',
'BrowserFetcher',
'Browser',
'BrowserContext',
'Page',
'WebWorker',
'Accessibility',
'Keyboard',
'Mouse',
'Touchscreen',
'Tracing',
'FileChooser',
'Dialog',
'ConsoleMessage',
'Frame',
'JSHandle',
'ElementHandle',
'HTTPRequest',
'HTTPResponse',
'SecurityDetails',
'Target',
'CDPSession',
'Coverage',
'TimeoutError',
'EventEmitter',
];
/** @type {typeof sidebarItems} */
const apiSidebarItems = [];
const categories = new Map();
for (const item of sidebarItems) {
assert(item.type === 'doc' && item.label);
const [namespace] = item.label.split('.');
if (!categories.has(namespace)) {
categories.set(namespace, [item]);
} else {
categories.get(namespace).push(item);
}
}
function addNamespace(namespace, target) {
let items = categories.get(namespace);
if (!items) {
throw new Error(`Namespace ${namespace} not found`);
}
items.sort((a, b) => {
return a.label.localeCompare(b.label);
});
const main = items.find(item => {
return item.label === namespace;
});
items = items.filter(item => {
return item !== main;
});
target.push({
type: 'category',
label: namespace,
items,
link: main
? {
type: 'doc',
id: main.id,
}
: undefined,
});
categories.delete(namespace);
const order = [
// PuppeteerNode and Puppeteer go first as the entrypoints into
// the Puppeteer API.
'PuppeteerNode',
'Puppeteer',
'BrowserFetcher',
'Browser',
'BrowserContext',
'Page',
'WebWorker',
'Accessibility',
'Keyboard',
'Mouse',
'Touchscreen',
'Tracing',
'FileChooser',
'Dialog',
'ConsoleMessage',
'Frame',
'JSHandle',
'ElementHandle',
'HTTPRequest',
'HTTPResponse',
'SecurityDetails',
'Target',
'CDPSession',
'Coverage',
'TimeoutError',
'EventEmitter',
];
function addNamespace(namespace, target) {
let items = categories.get(namespace);
if (!items) {
throw new Error(`Namespace ${namespace} not found`);
}
for (const namespace of order) {
addNamespace(namespace, newItems);
}
const otherItems = [];
newItems.push({
items.sort((a, b) => {
return a.label.localeCompare(b.label);
});
const main = items.find(item => {
return item.label === namespace;
});
items = items.filter(item => {
return item !== main;
});
target.push({
type: 'category',
label: 'Other',
items: otherItems,
label: namespace,
items,
link: main
? {
type: 'doc',
id: main.id,
}
: undefined,
});
const remaining = Array.from(categories.keys());
remaining.sort((a, b) => {
return a.localeCompare(b);
});
for (const namespace of remaining) {
addNamespace(namespace, otherItems);
}
apiCategoryItem.items = newItems;
apiCategoryItem.collapsed = false;
categories.delete(namespace);
}
const guidesCategory = sidebarItems.find(value => {
return value.type === 'category' && value.label === 'Guides';
for (const namespace of order) {
addNamespace(namespace, apiSidebarItems);
}
const otherItems = [];
apiSidebarItems.push({
type: 'category',
label: 'Other',
items: otherItems,
collapsed: true,
});
if (guidesCategory) {
guidesCategory.collapsed = false;
const remaining = Array.from(categories.keys());
remaining.sort((a, b) => {
return a.localeCompare(b);
});
for (const namespace of remaining) {
addNamespace(namespace, otherItems);
}
return sidebarItems;
return apiSidebarItems;
},
path: DOC_PATH,
routeBasePath: DOC_ROUTE_BASE_PATH,
sidebarPath: require.resolve('./sidebars.json'),
sidebarPath: require.resolve('./sidebars.js'),
},
theme: {
customCss: require.resolve('./src/css/custom.css'),
@ -182,7 +194,7 @@ const config = {
],
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
{
navbar: {
title: 'Puppeteer',
logo: {
@ -190,32 +202,53 @@ const config = {
src: 'https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png',
},
items: [
{
type: 'docsVersionDropdown',
position: 'right',
dropdownActiveClassDisabled: true,
dropdownItemsAfter: [
{
type: 'html',
value: '<hr class="dropdown-separator">',
},
{
type: 'html',
className: 'dropdown-archived-versions',
value: '<b>Archived versions</b>',
},
...archivedVersions.map(version => {
return {
label: version,
href: `https://github.com/puppeteer/puppeteer/blob/v${version}/docs/api/index.md`,
};
}),
],
},
{
type: 'search',
position: 'right',
},
...[
{
type: 'doc',
docId: 'index',
label: 'Docs',
},
{
type: 'docSidebar',
sidebarId: 'api',
label: 'API',
},
].map(item => {
return Object.assign(item, {position: 'left'});
}),
...[
{
type: 'docsVersionDropdown',
dropdownActiveClassDisabled: true,
dropdownItemsAfter: [
{
type: 'html',
value: '<hr class="dropdown-separator">',
},
{
type: 'html',
className: 'dropdown-archived-versions',
value: '<b>Archived versions</b>',
},
...archivedVersions.map(version => {
return {
label: version,
href: `https://github.com/puppeteer/puppeteer/blob/v${version}/docs/api/index.md`,
};
}),
],
},
{
type: 'search',
},
{
href: 'https://github.com/puppeteer/puppeteer',
className: 'header-github-link',
'aria-label': 'GitHub repository',
},
].map(item => {
return Object.assign(item, {position: 'right'});
}),
],
},
footer: {
@ -245,7 +278,7 @@ const config = {
theme: lightCodeTheme,
darkTheme: darkCodeTheme,
},
}),
},
themes: [
// ... Your other themes.
[

40
website/package-lock.json generated
View File

@ -9,6 +9,7 @@
"version": "0.0.0",
"dependencies": {
"@docusaurus/core": "2.1.0",
"@docusaurus/plugin-client-redirects": "^2.1.0",
"@docusaurus/preset-classic": "2.1.0",
"@easyops-cn/docusaurus-search-local": "0.33.4",
"@mdx-js/react": "1.6.22",
@ -2157,6 +2158,29 @@
"react-dom": "*"
}
},
"node_modules/@docusaurus/plugin-client-redirects": {
"version": "2.1.0",
"resolved": "https://registry.npmjs.org/@docusaurus/plugin-client-redirects/-/plugin-client-redirects-2.1.0.tgz",
"integrity": "sha512-3PhzwHSyZWqBAFPJuLJE3dZVuKWQEj9ReQP85Z3/2hpnQoVNBgAqc+64FIko0FvvK1iluLeasO7NWGyuATngvw==",
"dependencies": {
"@docusaurus/core": "2.1.0",
"@docusaurus/logger": "2.1.0",
"@docusaurus/utils": "2.1.0",
"@docusaurus/utils-common": "2.1.0",
"@docusaurus/utils-validation": "2.1.0",
"eta": "^1.12.3",
"fs-extra": "^10.1.0",
"lodash": "^4.17.21",
"tslib": "^2.4.0"
},
"engines": {
"node": ">=16.14"
},
"peerDependencies": {
"react": "^16.8.4 || ^17.0.0",
"react-dom": "^16.8.4 || ^17.0.0"
}
},
"node_modules/@docusaurus/plugin-content-blog": {
"version": "2.1.0",
"resolved": "https://registry.npmjs.org/@docusaurus/plugin-content-blog/-/plugin-content-blog-2.1.0.tgz",
@ -14477,6 +14501,22 @@
"react-loadable": "npm:@docusaurus/react-loadable@5.5.2"
}
},
"@docusaurus/plugin-client-redirects": {
"version": "2.1.0",
"resolved": "https://registry.npmjs.org/@docusaurus/plugin-client-redirects/-/plugin-client-redirects-2.1.0.tgz",
"integrity": "sha512-3PhzwHSyZWqBAFPJuLJE3dZVuKWQEj9ReQP85Z3/2hpnQoVNBgAqc+64FIko0FvvK1iluLeasO7NWGyuATngvw==",
"requires": {
"@docusaurus/core": "2.1.0",
"@docusaurus/logger": "2.1.0",
"@docusaurus/utils": "2.1.0",
"@docusaurus/utils-common": "2.1.0",
"@docusaurus/utils-validation": "2.1.0",
"eta": "^1.12.3",
"fs-extra": "^10.1.0",
"lodash": "^4.17.21",
"tslib": "^2.4.0"
}
},
"@docusaurus/plugin-content-blog": {
"version": "2.1.0",
"resolved": "https://registry.npmjs.org/@docusaurus/plugin-content-blog/-/plugin-content-blog-2.1.0.tgz",

1
website/package.json
View File

@ -16,6 +16,7 @@
},
"dependencies": {
"@docusaurus/core": "2.1.0",
"@docusaurus/plugin-client-redirects": "^2.1.0",
"@docusaurus/preset-classic": "2.1.0",
"@easyops-cn/docusaurus-search-local": "0.33.4",
"@mdx-js/react": "1.6.22",

33
website/sidebars.js Normal file
View File

@ -0,0 +1,33 @@
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
module.exports = {
docs: [
'index',
{
type: 'category',
label: 'Guides',
link: {
type: 'generated-index',
title: 'Puppeteer Guides',
keywords: ['guides'],
},
collapsed: false,
items: [
'guides/chrome-extensions',
'guides/configuration',
'guides/debugging',
'guides/docker',
'guides/request-interception',
],
},
'chromium-support',
'troubleshooting',
'contributing',
'faq',
],
api: [
{
type: 'autogenerated',
dirName: 'api',
},
],
};

8
website/sidebars.json
View File

@ -1,8 +0,0 @@
{
"sidebar": [
{
"type": "autogenerated",
"dirName": "."
}
]
}

27
website/src/css/custom.css
View File

@ -39,3 +39,30 @@
--ifm-color-primary-lightest: #4fddbf;
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
}
.header-github-link:hover {
opacity: 0.6;
}
.header-github-link::before {
content: '';
width: 24px;
height: 24px;
display: flex;
background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E")
no-repeat;
}
[data-theme='dark'] .header-github-link::before {
background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill='white' d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E")
no-repeat;
}
.dropdown-separator {
margin: 0.3rem 0;
}
.dropdown-archived-versions {
font-size: 0.875rem;
padding: 0.2rem 0.5rem;
}

4
website/versioned_docs/version-19.2.0/chromium-support.md
View File

@ -1,7 +1,3 @@
---
sidebar_position: 6
---
# Chromium Support
The following versions of Chromium are supported, mapped to Puppeteer version:

7
website/versioned_docs/version-19.2.0/contributing.md
View File

@ -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,

4
website/versioned_docs/version-19.2.0/faq.md
View File

@ -1,7 +1,3 @@
---
sidebar_position: 3
---
# FAQ
## Q: Who maintains Puppeteer?

6
website/versioned_docs/version-19.2.0/guides/_category_.yml
View File

@ -1,6 +0,0 @@
label: Guides
position: 2
collapsed: false
link:
type: generated-index
title: Puppeteer Guides

17
docs/guides/configuring-puppeteer.mdx → website/versioned_docs/version-19.2.0/guides/configuration.mdx
View File

@ -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

31
website/versioned_docs/version-19.2.0/guides/debugging.md
View File

@ -27,10 +27,10 @@ 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});
@ -38,9 +38,9 @@ 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

32
website/versioned_docs/version-19.2.0/index.md
View File

@ -1,7 +1,3 @@
---
sidebar_position: 1
---
# Puppeteer
[![Build status](https://github.com/puppeteer/puppeteer/workflows/CI/badge.svg)](https://github.com/puppeteer/puppeteer/actions?query=workflow%3ACI)
@ -9,7 +5,7 @@ sidebar_position: 1
<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)

8
website/versioned_docs/version-19.2.0/troubleshooting.md
View File

@ -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

30
website/versioned_sidebars/version-19.2.0-sidebars.json
View File

@ -1,8 +1,34 @@
{
"sidebar": [
"docs": [
"index",
{
"type": "category",
"label": "Guides",
"link": {
"type": "generated-index",
"title": "Puppeteer Guides",
"keywords": [
"guides"
]
},
"collapsed": false,
"items": [
"guides/chrome-extensions",
"guides/configuration",
"guides/debugging",
"guides/docker",
"guides/request-interception"
]
},
"chromium-support",
"troubleshooting",
"contributing",
"faq"
],
"api": [
{
"type": "autogenerated",
"dirName": "."
"dirName": "api"
}
]
}