Skip to content

condorheroblog/html-export-pdf-cli

Repository files navigation

html-export-pdf-cli

NPM version NPM Downloads LICENSE GitHub stars

Render HTML to PDF(with outline) using Puppeteer.

Features

  • πŸ–₯️ Converting HTML to PDF for .html, .htm, .xhtml file formats
  • πŸ“‘ Added PDF outline
  • βš™οΈ Configurations for generating PDF with Puppeteer β€”β€” pdfOptions
  • πŸ“‚ Multi-file PDF generation
  • ⌨️ Developed in TypeScript
  • ⏬ Download web page

Installation

# Global installation
npm install -g html-export-pdf-cli

# Local installation
npm install --save-dev html-export-pdf-cli

The installed html-export-pdf-cli command is available.

Usage

Generating a PDF

html-export-pdf-cli ./index.html -o result.pdf

Generating two PDFs

html-export-pdf-cli ./index.html ./home.html
# or
html-export-pdf-cli -t ./index.html -t ./home.html
html-export-pdf-cli --inputs ./index.html --inputs ./home.html

Generating some PDFs

This Library uses glob to parse the path you enter, and its syntax refers to the glob documentation.

html-export-pdf-cli ./pdf/*.html

Outline

html-export-pdf-cli ./index.html --outlineTags h1,h2 -o index.pdf

Using outlineContainerSelector specify an outline container selector

html-export-pdf-cli ./index.html --outlineContainerSelector .VPDoc --outlineTags h1,h2 -o index.pdf

Additional Scripts

html-export-pdf-cli ./index.html --additionalScripts a.js --additionalScripts b.js -o index.pdf

Additional Styles

html-export-pdf-cli ./index.html --additionalStyles a.css --additionalStyles b.css -o index.pdf

PDF Options

You can customize all configuration parameters for Puppeteer to generate PDF except path.

Property Modifiers Type Description Default
footerTemplate optional string HTML template for the print footer. Has the same constraints and support for special classes as PDFOptions.headerTemplate.
format optional PaperFormat letter.
headerTemplate optional string

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

height optional string | number Sets the height of paper. You can pass in a number or a string with a unit.
landscape optional boolean Whether to print in landscape orientation. false
margin optional PDFMargin Set the PDF margins. undefined no margins are set.
omitBackground optional boolean Hides default white background and allows generating PDFs with transparency. false
pageRanges optional string Paper ranges to print, e.g. 1-5, 8, 11-13. The empty string, which means all pages are printed.
preferCSSPageSize optional boolean Give any CSS @page size declared in the page priority over what is declared in the width or height or format option. false, which will scale the content to fit the paper size.
printBackground optional boolean Set to true to print background graphics. false
scale optional number Scales the rendering of the web page. Amount must be between 0.1 and 2. 1
timeout optional number Timeout in milliseconds. Pass 0 to disable timeout. 30_000
width optional string | number Sets the width of paper. You can pass in a number or a string with a unit.

Format

html-export-pdf-cli ./index.html -s A0 -o index.pdf
# or
html-export-pdf-cli ./index.html --pageSize A0 -o index.pdf

Margin

html-export-pdf-cli ./index.html -m top=10,bottom=10,left=10,right=10 -o index.pdf
# or
html-export-pdf-cli ./index.html --margin top=10,bottom=10,left=10,right=10 -o index.pdf

The order can be customized, even omitting a few.

html-export-pdf-cli ./index.html -m top=10 -o index.pdf
html-export-pdf-cli ./index.html -m right=10 -o index.pdf
html-export-pdf-cli ./index.html -m right=10,left=10 -o index.pdf
html-export-pdf-cli ./index.html -m top=10,left=10 -o index.pdf

Page Ranges

html-export-pdf-cli ./index.html --pageRanges 1-5 -o index.pdf

OmitBackground

html-export-pdf-cli ./index.html --omitBackground -o index.pdf

etc.

PDF File Name Convention

Rules for automatically generating PDF file names.

URL Filename
https://www.example.com/ www.example.com.pdf
https://www.example.com:80/ www.example.com.pdf
https://www.example.com/resource resource.pdf
https://www.example.com/resource.extension resource.pdf
https://www.example.com/path/ path.pdf
https://www.example.com/path/to/ path_to.pdf
https://www.example.com/path/to/resource resource.pdf
https://www.example.com/path/to/resource.ext resource.pdf
file:///User/path/to/resource.html resource.pdf

Options

Key Type CLI option Description Default Value
inputs string[] --inputs Input one or more local or online paths. []
outFile string --outFile Output file name. {input}.pdf
outDir string --outDir Output directory. process.cwd()
headless boolean | shell --headless Whether to run the browser in headless mode. true
PDFOptions object Valid options to configure PDF generation via Page.pdf().
β”— scale number --scale Scales the rendering of the web page. Amount must be between 0.1 and 2. 1
β”— headerTemplate string --headerTemplate HTML template for the print header.
β”— footerTemplate string --footerTemplate HTML template for the print footer.
β”— preferCSSPageSize boolean --preferCSSPageSize Give any CSS @page size declared in the page priority over what is declared in the width or height or format option. false
β”— printBackground boolean --printBackground Set to print background graphics. false
β”— omitBackground boolean --omitBackground Hides default white background and allows generating PDFs with transparency. false
β”— pageRanges string --pageRanges Paper ranges to print, e.g. 1-5, 8, 11-13.
β”— margin object -m, --margin Set the PDF margins. e.g. top=10,bottom=10,left=10,right=10.
β”— landscape boolean -l, --landscape Whether to print in landscape orientation. false
β”— pageSize string -s, --page-size Print to Page Size [size]. letter
β”— width string | number -w, --width Print to Page Width [width] in MM.
β”— height string | number -h, --height Print to Page Height [height] in MM.
β”— timeout number -t, --timeout Set a max timeout of [ms].
html boolean -x, --html Output html file.
blockLocal boolean -b, --blockLocal Disallow access to filesystem for local files. false
blockRemote boolean -r, --blockRemote Disallow requests to remote servers. false
outlineContainerSelector string --outlineContainerSelector Specify an outline container selector.
allowedPaths string[] --allowedPaths Only allow access to given filesystem paths, repeatable. []
ignoreHTTPSErrors boolean --ignoreHTTPSErrors Whether to ignore HTTPS errors during navigation. false
allowedDomains string[] --allowedDomains Only allow access to given remote domains, repeatable. []
outlineTags string[] --outline-tags Add outlines (bookmarks) to PDF. [h1,h2,h3,h4,h5,h6]
additionalScripts string[] --additional-scripts additional script tags to the HTML document. []
additionalStyles string[] --additional-styles additional style tags to the HTML document. []
browserEndpoint string --browserEndpoint Use a remote Chrome server with browserWSEndpoint.
browserArgs string[] --browserArgs Launch Chrome with comma separated args. []
media string --media Emulate print or screen media, defaults to print. print
debug boolean --debug Debug. false
warn boolean --warn Enable warning logs. false

License

This library is under the MIT License.