chore(docs): migrate page.pdf() docs (#6228)

Also took the opportunity to pull out the PDF types into their own file to clear up `Page.ts` slightly and give the PDF code a more natural place to live.
puppeteer · Jul 17, 2020 · 9fdf2ba · 9fdf2ba
1 parent 2331584
commit 9fdf2ba
Show file tree

Hide file tree

Showing 29 changed files with 587 additions and 47 deletions.
diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md
@@ -69,6 +69,8 @@
 |  [Metrics](./puppeteer.metrics.md) |  |
 |  [MouseOptions](./puppeteer.mouseoptions.md) |  |
 |  [MouseWheelOptions](./puppeteer.mousewheeloptions.md) |  |
+|  [PDFMargin](./puppeteer.pdfmargin.md) |  |
+|  [PDFOptions](./puppeteer.pdfoptions.md) | Valid options to configure PDF generation via [Page.pdf()](./puppeteer.page.pdf.md)<!-- -->. |
 |  [PressOptions](./puppeteer.pressoptions.md) |  |
 |  [ProductLauncher](./puppeteer.productlauncher.md) | Describes a launcher - a class that is able to create and launch a browser instance. |
 |  [RemoteAddress](./puppeteer.remoteaddress.md) |  |
@@ -108,6 +110,7 @@
 |  [JSONArray](./puppeteer.jsonarray.md) |  |
 |  [KeyInput](./puppeteer.keyinput.md) | All the valid keys that can be passed to functions that take user input, such as [keyboard.press](./puppeteer.keyboard.press.md) |
 |  [MouseButton](./puppeteer.mousebutton.md) |  |
+|  [PaperFormat](./puppeteer.paperformat.md) | All the valid paper format types when printing a PDF. |
 |  [Platform](./puppeteer.platform.md) | Supported platforms. |
 |  [Product](./puppeteer.product.md) | Supported products. |
 |  [PuppeteerErrors](./puppeteer.puppeteererrors.md) |  |

diff --git a/new-docs/puppeteer.page.md b/new-docs/puppeteer.page.md
@@ -107,8 +107,8 @@ page.off('request', logRequest);
 |  [isJavaScriptEnabled()](./puppeteer.page.isjavascriptenabled.md) |  |  |
 |  [mainFrame()](./puppeteer.page.mainframe.md) |  |  |
 |  [metrics()](./puppeteer.page.metrics.md) |  |  |
-|  [pdf(options)](./puppeteer.page.pdf.md) |  |  |
-|  [queryObjects(prototypeHandle)](./puppeteer.page.queryobjects.md) |  |  |
+|  [pdf(options)](./puppeteer.page.pdf.md) |  | Generatees a PDF of the page with the <code>print</code> CSS media type. |
+|  [queryObjects(prototypeHandle)](./puppeteer.page.queryobjects.md) |  | This method iterates the JavaScript heap and finds all objects with the given prototype. |
 |  [reload(options)](./puppeteer.page.reload.md) |  |  |
 |  [screenshot(options)](./puppeteer.page.screenshot.md) |  |  |
 |  [select(selector, values)](./puppeteer.page.select.md) |  |  |

diff --git a/new-docs/puppeteer.page.pdf.md b/new-docs/puppeteer.page.pdf.md
@@ -4,6 +4,8 @@
 
 ## Page.pdf() method
 
+Generatees a PDF of the page with the `print` CSS media type.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,9 +16,17 @@ pdf(options?: PDFOptions): Promise<Buffer>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | PDFOptions |  |
+|  options | [PDFOptions](./puppeteer.pdfoptions.md) | options for generating the PDF. |
 
 <b>Returns:</b>
 
 Promise&lt;Buffer&gt;
 
+## Remarks
+
+IMPORTANT: PDF generation is only supported in Chrome headless mode.
+
+To generate a PDF with the `screen` media type, call [\`page.emulateMediaType('screen')\`](./puppeteer.page.emulatemediatype.md) before calling `page.pdf()`<!-- -->.
+
+By default, `page.pdf()` generates a pdf with modified colors for printing. Use the [\`-webkit-print-color-adjust\`](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-print-color-adjust) property to force rendering of exact colors.
+
diff --git a/new-docs/puppeteer.page.queryobjects.md b/new-docs/puppeteer.page.queryobjects.md
@@ -4,6 +4,8 @@
 
 ## Page.queryObjects() method
 
+This method iterates the JavaScript heap and finds all objects with the given prototype.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,9 +16,29 @@ queryObjects(prototypeHandle: JSHandle): Promise<JSHandle>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  prototypeHandle | [JSHandle](./puppeteer.jshandle.md) |  |
+|  prototypeHandle | [JSHandle](./puppeteer.jshandle.md) | a handle to the object prototype. |
 
 <b>Returns:</b>
 
 Promise&lt;[JSHandle](./puppeteer.jshandle.md)<!-- -->&gt;
 
+## Remarks
+
+
+## Example
+
+
+```js
+// Create a Map object
+await page.evaluate(() => window.map = new Map());
+// Get a handle to the Map object prototype
+const mapPrototype = await page.evaluateHandle(() => Map.prototype);
+// Query all map instances into an array
+const mapInstances = await page.queryObjects(mapPrototype);
+// Count amount of map objects in heap
+const count = await page.evaluate(maps => maps.length, mapInstances);
+await mapInstances.dispose();
+await mapPrototype.dispose();
+
+```
+
diff --git a/new-docs/puppeteer.paperformat.md b/new-docs/puppeteer.paperformat.md
@@ -0,0 +1,38 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PaperFormat](./puppeteer.paperformat.md)
+
+## PaperFormat type
+
+All the valid paper format types when printing a PDF.
+
+<b>Signature:</b>
+
+```typescript
+export declare type PaperFormat = 'letter' | 'legal' | 'tabloid' | 'ledger' | 'a0' | 'a1' | 'a2' | 'a3' | 'a4' | 'a5' | 'a6';
+```
+
+## Remarks
+
+The sizes of each format are as follows: - `Letter`<!-- -->: 8.5in x 11in
+
+- `Legal`<!-- -->: 8.5in x 14in
+
+- `Tabloid`<!-- -->: 11in x 17in
+
+- `Ledger`<!-- -->: 17in x 11in
+
+- `A0`<!-- -->: 33.1in x 46.8in
+
+- `A1`<!-- -->: 23.4in x 33.1in
+
+- `A2`<!-- -->: 16.54in x 23.4in
+
+- `A3`<!-- -->: 11.7in x 16.54in
+
+- `A4`<!-- -->: 8.27in x 11.7in
+
+- `A5`<!-- -->: 5.83in x 8.27in
+
+- `A6`<!-- -->: 4.13in x 5.83in
+
diff --git a/new-docs/puppeteer.pdfmargin.bottom.md b/new-docs/puppeteer.pdfmargin.bottom.md
@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFMargin](./puppeteer.pdfmargin.md) &gt; [bottom](./puppeteer.pdfmargin.bottom.md)
+
+## PDFMargin.bottom property
+
+<b>Signature:</b>
+
+```typescript
+bottom?: string | number;
+```
diff --git a/new-docs/puppeteer.pdfmargin.left.md b/new-docs/puppeteer.pdfmargin.left.md
@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFMargin](./puppeteer.pdfmargin.md) &gt; [left](./puppeteer.pdfmargin.left.md)
+
+## PDFMargin.left property
+
+<b>Signature:</b>
+
+```typescript
+left?: string | number;
+```
diff --git a/new-docs/puppeteer.pdfmargin.md b/new-docs/puppeteer.pdfmargin.md
@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFMargin](./puppeteer.pdfmargin.md)
+
+## PDFMargin interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface PDFMargin 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [bottom](./puppeteer.pdfmargin.bottom.md) | string \| number |  |
+|  [left](./puppeteer.pdfmargin.left.md) | string \| number |  |
+|  [right](./puppeteer.pdfmargin.right.md) | string \| number |  |
+|  [top](./puppeteer.pdfmargin.top.md) | string \| number |  |
+
diff --git a/new-docs/puppeteer.pdfmargin.right.md b/new-docs/puppeteer.pdfmargin.right.md
@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFMargin](./puppeteer.pdfmargin.md) &gt; [right](./puppeteer.pdfmargin.right.md)
+
+## PDFMargin.right property
+
+<b>Signature:</b>
+
+```typescript
+right?: string | number;
+```
diff --git a/new-docs/puppeteer.pdfmargin.top.md b/new-docs/puppeteer.pdfmargin.top.md
@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFMargin](./puppeteer.pdfmargin.md) &gt; [top](./puppeteer.pdfmargin.top.md)
+
+## PDFMargin.top property
+
+<b>Signature:</b>
+
+```typescript
+top?: string | number;
+```
diff --git a/new-docs/puppeteer.pdfoptions.displayheaderfooter.md b/new-docs/puppeteer.pdfoptions.displayheaderfooter.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFOptions](./puppeteer.pdfoptions.md) &gt; [displayHeaderFooter](./puppeteer.pdfoptions.displayheaderfooter.md)
+
+## PDFOptions.displayHeaderFooter property
+
+Whether to show the header and footer.
+
+<b>Signature:</b>
+
+```typescript
+displayHeaderFooter?: boolean;
+```
diff --git a/new-docs/puppeteer.pdfoptions.footertemplate.md b/new-docs/puppeteer.pdfoptions.footertemplate.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFOptions](./puppeteer.pdfoptions.md) &gt; [footerTemplate](./puppeteer.pdfoptions.footertemplate.md)
+
+## PDFOptions.footerTemplate property
+
+HTML template for the print footer. Has the same constraints and support for special classes as [PDFOptions.headerTemplate](./puppeteer.pdfoptions.headertemplate.md)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+footerTemplate?: string;
+```
diff --git a/new-docs/puppeteer.pdfoptions.format.md b/new-docs/puppeteer.pdfoptions.format.md
@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFOptions](./puppeteer.pdfoptions.md) &gt; [format](./puppeteer.pdfoptions.format.md)
+
+## PDFOptions.format property
+
+<b>Signature:</b>
+
+```typescript
+format?: PaperFormat;
+```
+
+## Remarks
+
+If set, this takes priority over the `width` and `height` options.
+
diff --git a/new-docs/puppeteer.pdfoptions.headertemplate.md b/new-docs/puppeteer.pdfoptions.headertemplate.md
@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFOptions](./puppeteer.pdfoptions.md) &gt; [headerTemplate](./puppeteer.pdfoptions.headertemplate.md)
+
+## PDFOptions.headerTemplate property
+
+HTML template for the print header. Should be valid HTML with the following classes used to inject values into them: - `date` formatted print date
+
+- `title` document title
+
+- `url` document location
+
+- `pageNumber` current page number
+
+- `totalPages` total pages in the document
+
+<b>Signature:</b>
+
+```typescript
+headerTemplate?: string;
+```
diff --git a/new-docs/puppeteer.pdfoptions.height.md b/new-docs/puppeteer.pdfoptions.height.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFOptions](./puppeteer.pdfoptions.md) &gt; [height](./puppeteer.pdfoptions.height.md)
+
+## PDFOptions.height property
+
+Sets the height of paper. You can pass in a number or a string with a unit.
+
+<b>Signature:</b>
+
+```typescript
+height?: string | number;
+```
diff --git a/new-docs/puppeteer.pdfoptions.landscape.md b/new-docs/puppeteer.pdfoptions.landscape.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFOptions](./puppeteer.pdfoptions.md) &gt; [landscape](./puppeteer.pdfoptions.landscape.md)
+
+## PDFOptions.landscape property
+
+Whether to print in landscape orientation.
+
+<b>Signature:</b>
+
+```typescript
+landscape?: boolean;
+```
diff --git a/new-docs/puppeteer.pdfoptions.margin.md b/new-docs/puppeteer.pdfoptions.margin.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFOptions](./puppeteer.pdfoptions.md) &gt; [margin](./puppeteer.pdfoptions.margin.md)
+
+## PDFOptions.margin property
+
+Set the PDF margins.
+
+<b>Signature:</b>
+
+```typescript
+margin?: PDFMargin;
+```
diff --git a/new-docs/puppeteer.pdfoptions.md b/new-docs/puppeteer.pdfoptions.md
@@ -0,0 +1,32 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFOptions](./puppeteer.pdfoptions.md)
+
+## PDFOptions interface
+
+Valid options to configure PDF generation via [Page.pdf()](./puppeteer.page.pdf.md)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+export interface PDFOptions 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [displayHeaderFooter](./puppeteer.pdfoptions.displayheaderfooter.md) | boolean | Whether to show the header and footer. |
+|  [footerTemplate](./puppeteer.pdfoptions.footertemplate.md) | string | HTML template for the print footer. Has the same constraints and support for special classes as [PDFOptions.headerTemplate](./puppeteer.pdfoptions.headertemplate.md)<!-- -->. |
+|  [format](./puppeteer.pdfoptions.format.md) | [PaperFormat](./puppeteer.paperformat.md) |  |
+|  [headerTemplate](./puppeteer.pdfoptions.headertemplate.md) | string | HTML template for the print header. Should be valid HTML with the following classes used to inject values into them: - <code>date</code> formatted print date<!-- -->- <code>title</code> document title<!-- -->- <code>url</code> document location<!-- -->- <code>pageNumber</code> current page number<!-- -->- <code>totalPages</code> total pages in the document |
+|  [height](./puppeteer.pdfoptions.height.md) | string \| number | Sets the height of paper. You can pass in a number or a string with a unit. |
+|  [landscape](./puppeteer.pdfoptions.landscape.md) | boolean | Whether to print in landscape orientation. |
+|  [margin](./puppeteer.pdfoptions.margin.md) | [PDFMargin](./puppeteer.pdfmargin.md) | Set the PDF margins. |
+|  [pageRanges](./puppeteer.pdfoptions.pageranges.md) | string | Paper ranges to print, e.g. <code>1-5, 8, 11-13</code>. |
+|  [path](./puppeteer.pdfoptions.path.md) | string | The path to save the file to. |
+|  [preferCSSPageSize](./puppeteer.pdfoptions.prefercsspagesize.md) | boolean | Give any CSS <code>@page</code> size declared in the page priority over what is declared in the <code>width</code> or <code>height</code> or <code>format</code> option. |
+|  [printBackground](./puppeteer.pdfoptions.printbackground.md) | boolean | Set to <code>true</code> to print background graphics. |
+|  [scale](./puppeteer.pdfoptions.scale.md) | number | Scales the rendering of the web page. Amount must be between <code>0.1</code> and <code>2</code>. |
+|  [width](./puppeteer.pdfoptions.width.md) | string \| number | Sets the width of paper. You can pass in a number or a string with a unit. |
+
diff --git a/new-docs/puppeteer.pdfoptions.pageranges.md b/new-docs/puppeteer.pdfoptions.pageranges.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFOptions](./puppeteer.pdfoptions.md) &gt; [pageRanges](./puppeteer.pdfoptions.pageranges.md)
+
+## PDFOptions.pageRanges property
+
+Paper ranges to print, e.g. `1-5, 8, 11-13`<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+pageRanges?: string;
+```
diff --git a/new-docs/puppeteer.pdfoptions.path.md b/new-docs/puppeteer.pdfoptions.path.md
@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFOptions](./puppeteer.pdfoptions.md) &gt; [path](./puppeteer.pdfoptions.path.md)
+
+## PDFOptions.path property
+
+The path to save the file to.
+
+<b>Signature:</b>
+
+```typescript
+path?: string;
+```
+
+## Remarks
+
+If the path is relative, it's resolved relative to the current working directory.
+
diff --git a/new-docs/puppeteer.pdfoptions.prefercsspagesize.md b/new-docs/puppeteer.pdfoptions.prefercsspagesize.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PDFOptions](./puppeteer.pdfoptions.md) &gt; [preferCSSPageSize](./puppeteer.pdfoptions.prefercsspagesize.md)
+
+## PDFOptions.preferCSSPageSize property
+
+Give any CSS `@page` size declared in the page priority over what is declared in the `width` or `height` or `format` option.
+
+<b>Signature:</b>
+
+```typescript
+preferCSSPageSize?: boolean;
+```