docs: improve docs (#9179)
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 
This commit is contained in:
jrandolf
GitHub
parent
f3ff18e468
commit
2d2120cea1
33
README.md
33
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)
|
||||
|
||||
|
||||
@ -1,7 +1,3 @@
|
||||
---
|
||||
sidebar_position: 6
|
||||
---
|
||||
|
||||
# Chromium Support
|
||||
|
||||
The following versions of Chromium are supported, mapped to Puppeteer version:
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -1,7 +1,3 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# FAQ
|
||||
|
||||
## Q: Who maintains Puppeteer?
|
||||
|
||||
@ -1,6 +0,0 @@
|
||||
label: Guides
|
||||
position: 2
|
||||
collapsed: false
|
||||
link:
|
||||
type: generated-index
|
||||
title: Puppeteer Guides
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -1,7 +1,3 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Puppeteer
|
||||
|
||||
[](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)
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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'])
|
||||
|
||||
@ -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,14 +84,18 @@ 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) {
|
||||
if (!apiItem) {
|
||||
return sidebarItems;
|
||||
}
|
||||
|
||||
/** @type {typeof sidebarItems} */
|
||||
const newItems = [];
|
||||
const apiSidebarItems = [];
|
||||
const categories = new Map();
|
||||
for (const item of apiCategoryItem.items) {
|
||||
for (const item of sidebarItems) {
|
||||
assert(item.type === 'doc' && item.label);
|
||||
const [namespace] = item.label.split('.');
|
||||
if (!categories.has(namespace)) {
|
||||
categories.set(namespace, [item]);
|
||||
@ -143,14 +162,16 @@ const config = {
|
||||
});
|
||||
categories.delete(namespace);
|
||||
}
|
||||
|
||||
for (const namespace of order) {
|
||||
addNamespace(namespace, newItems);
|
||||
addNamespace(namespace, apiSidebarItems);
|
||||
}
|
||||
const otherItems = [];
|
||||
newItems.push({
|
||||
apiSidebarItems.push({
|
||||
type: 'category',
|
||||
label: 'Other',
|
||||
items: otherItems,
|
||||
collapsed: true,
|
||||
});
|
||||
const remaining = Array.from(categories.keys());
|
||||
remaining.sort((a, b) => {
|
||||
@ -159,20 +180,11 @@ const config = {
|
||||
for (const namespace of remaining) {
|
||||
addNamespace(namespace, otherItems);
|
||||
}
|
||||
apiCategoryItem.items = newItems;
|
||||
apiCategoryItem.collapsed = false;
|
||||
}
|
||||
const guidesCategory = sidebarItems.find(value => {
|
||||
return value.type === 'category' && value.label === 'Guides';
|
||||
});
|
||||
if (guidesCategory) {
|
||||
guidesCategory.collapsed = false;
|
||||
}
|
||||
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,9 +202,23 @@ const config = {
|
||||
src: 'https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png',
|
||||
},
|
||||
items: [
|
||||
...[
|
||||
{
|
||||
type: 'doc',
|
||||
docId: 'index',
|
||||
label: 'Docs',
|
||||
},
|
||||
{
|
||||
type: 'docSidebar',
|
||||
sidebarId: 'api',
|
||||
label: 'API',
|
||||
},
|
||||
].map(item => {
|
||||
return Object.assign(item, {position: 'left'});
|
||||
}),
|
||||
...[
|
||||
{
|
||||
type: 'docsVersionDropdown',
|
||||
position: 'right',
|
||||
dropdownActiveClassDisabled: true,
|
||||
dropdownItemsAfter: [
|
||||
{
|
||||
@ -214,8 +240,15 @@ const config = {
|
||||
},
|
||||
{
|
||||
type: 'search',
|
||||
position: 'right',
|
||||
},
|
||||
{
|
||||
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
40
website/package-lock.json
generated
@ -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",
|
||||
|
||||
@ -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
33
website/sidebars.js
Normal 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',
|
||||
},
|
||||
],
|
||||
};
|
||||
@ -1,8 +0,0 @@
|
||||
{
|
||||
"sidebar": [
|
||||
{
|
||||
"type": "autogenerated",
|
||||
"dirName": "."
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -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;
|
||||
}
|
||||
|
||||
@ -1,7 +1,3 @@
|
||||
---
|
||||
sidebar_position: 6
|
||||
---
|
||||
|
||||
# Chromium Support
|
||||
|
||||
The following versions of Chromium are supported, mapped to Puppeteer version:
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -1,7 +1,3 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# FAQ
|
||||
|
||||
## Q: Who maintains Puppeteer?
|
||||
|
||||
@ -1,6 +0,0 @@
|
||||
label: Guides
|
||||
position: 2
|
||||
collapsed: false
|
||||
link:
|
||||
type: generated-index
|
||||
title: Puppeteer Guides
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -1,7 +1,3 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Puppeteer
|
||||
|
||||
[](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)
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user