diff --git a/.prettierrc.cjs b/.prettierrc.cjs index 01c7bea503a..46c608ced5a 100644 --- 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 index 7b2f6aea887..bb32d151c8b 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ -#### [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 index d1f7007c2f2..f136f5eddbb 100644 --- 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 index 3fd4a05ee91..ce261573c86 100644 --- 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 index 6c948338b67..1c8caf144b8 100644 --- 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 deleted file mode 100644 index e5b51ae9c33..00000000000 --- a/docs/guides/_category_.yml +++ /dev/null @@ -1,6 +0,0 @@ -label: Guides -position: 2 -collapsed: false -link: - type: generated-index - title: Puppeteer Guides diff --git a/website/versioned_docs/version-19.2.0/guides/configuring-puppeteer.mdx b/docs/guides/configuration.mdx similarity index 87% rename from website/versioned_docs/version-19.2.0/guides/configuring-puppeteer.mdx rename to docs/guides/configuration.mdx index c1b12f53a25..a94e2058694 100644 --- a/website/versioned_docs/version-19.2.0/guides/configuring-puppeteer.mdx +++ b/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 index 4b6d23ecefd..d66e04d520b 100644 --- a/docs/guides/debugging.md +++ b/docs/guides/debugging.md @@ -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 diff --git a/docs/index.md b/docs/index.md index aa1e8712ad3..77662af70c8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 -#### [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 index 8394b6bdff8..8bc91b8de06 100644 --- 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 index d20a85d3273..9808495a430 100644 --- 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']) diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index f0fe303d68d..e2387baecbd 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -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: '
', - }, - { - type: 'html', - className: 'dropdown-archived-versions', - value: 'Archived versions', - }, - ...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: '
', + }, + { + type: 'html', + className: 'dropdown-archived-versions', + value: 'Archived versions', + }, + ...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. [ diff --git a/website/package-lock.json b/website/package-lock.json index f5000e8f42d..7f362227f6d 100644 --- a/website/package-lock.json +++ b/website/package-lock.json @@ -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", diff --git a/website/package.json b/website/package.json index b2699876453..83b8dd45b2d 100644 --- a/website/package.json +++ b/website/package.json @@ -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", diff --git a/website/sidebars.js b/website/sidebars.js new file mode 100644 index 00000000000..7cb8bfe2b37 --- /dev/null +++ b/website/sidebars.js @@ -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', + }, + ], +}; diff --git a/website/sidebars.json b/website/sidebars.json deleted file mode 100644 index 2782dc0f445..00000000000 --- a/website/sidebars.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "sidebar": [ - { - "type": "autogenerated", - "dirName": "." - } - ] -} diff --git a/website/src/css/custom.css b/website/src/css/custom.css index 01a8f71d3a4..3a8b4f9eaab 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -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; +} diff --git a/website/versioned_docs/version-19.2.0/chromium-support.md b/website/versioned_docs/version-19.2.0/chromium-support.md index d1f7007c2f2..f136f5eddbb 100644 --- a/website/versioned_docs/version-19.2.0/chromium-support.md +++ b/website/versioned_docs/version-19.2.0/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/website/versioned_docs/version-19.2.0/contributing.md b/website/versioned_docs/version-19.2.0/contributing.md index 3fd4a05ee91..ce261573c86 100644 --- a/website/versioned_docs/version-19.2.0/contributing.md +++ b/website/versioned_docs/version-19.2.0/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/website/versioned_docs/version-19.2.0/faq.md b/website/versioned_docs/version-19.2.0/faq.md index 6c948338b67..1c8caf144b8 100644 --- a/website/versioned_docs/version-19.2.0/faq.md +++ b/website/versioned_docs/version-19.2.0/faq.md @@ -1,7 +1,3 @@ ---- -sidebar_position: 3 ---- - # FAQ ## Q: Who maintains Puppeteer? diff --git a/website/versioned_docs/version-19.2.0/guides/_category_.yml b/website/versioned_docs/version-19.2.0/guides/_category_.yml deleted file mode 100644 index e5b51ae9c33..00000000000 --- a/website/versioned_docs/version-19.2.0/guides/_category_.yml +++ /dev/null @@ -1,6 +0,0 @@ -label: Guides -position: 2 -collapsed: false -link: - type: generated-index - title: Puppeteer Guides diff --git a/docs/guides/configuring-puppeteer.mdx b/website/versioned_docs/version-19.2.0/guides/configuration.mdx similarity index 87% rename from docs/guides/configuring-puppeteer.mdx rename to website/versioned_docs/version-19.2.0/guides/configuration.mdx index c1b12f53a25..a94e2058694 100644 --- a/docs/guides/configuring-puppeteer.mdx +++ b/website/versioned_docs/version-19.2.0/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/website/versioned_docs/version-19.2.0/guides/debugging.md b/website/versioned_docs/version-19.2.0/guides/debugging.md index 4b6d23ecefd..d66e04d520b 100644 --- a/website/versioned_docs/version-19.2.0/guides/debugging.md +++ b/website/versioned_docs/version-19.2.0/guides/debugging.md @@ -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 diff --git a/website/versioned_docs/version-19.2.0/index.md b/website/versioned_docs/version-19.2.0/index.md index aa1e8712ad3..77662af70c8 100644 --- a/website/versioned_docs/version-19.2.0/index.md +++ b/website/versioned_docs/version-19.2.0/index.md @@ -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 -#### [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/website/versioned_docs/version-19.2.0/troubleshooting.md b/website/versioned_docs/version-19.2.0/troubleshooting.md index 8394b6bdff8..8bc91b8de06 100644 --- a/website/versioned_docs/version-19.2.0/troubleshooting.md +++ b/website/versioned_docs/version-19.2.0/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/website/versioned_sidebars/version-19.2.0-sidebars.json b/website/versioned_sidebars/version-19.2.0-sidebars.json index 2782dc0f445..cd264edc690 100644 --- a/website/versioned_sidebars/version-19.2.0-sidebars.json +++ b/website/versioned_sidebars/version-19.2.0-sidebars.json @@ -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" } ] }