Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
WKHTMLTOPDF(1)		    General Commands Manual		WKHTMLTOPDF(1)

Name
       wkhtmltopdf - html to pdf converter

Synopsis
	 wkhtmltopdf [GLOBAL OPTION]...	[OBJECT]... <output file>

Document objects
       wkhtmltopdf is able to put several objects into the output file,	an ob-
       ject is either a	single webpage,	a cover	webpage	or  a  table  of  con-
       tents.	The objects are	put into the output document in	the order they
       are specified on	the command line, options can be specified  on	a  per
       object basis or in the global options area. Options from	the Global Op-
       tions section can only be placed	in the global options area.

       A page objects puts the content of a single  webpage  into  the	output
       document.

	 (page)? <input	url/file name> [PAGE OPTION]...

       Options for the page object can be placed in the	global options and the
       page options areas. The applicable options can be found in the Page Op-
       tions and Headers And Footer Options sections.

       A  cover	 objects  puts the content of a	single webpage into the	output
       document, the page does not appear in the table of contents,  and  does
       not have	headers	and footers.

	 cover <input url/file name> [PAGE OPTION]...

       All  options that can be	specified for a	page object can	also be	speci-
       fied for	a cover.

       A table of contents object inserts a table of contents into the	output
       document.

	 toc [TOC OPTION]...

       All  options that can be	specified for a	page object can	also be	speci-
       fied for	a toc, further more the	options	from the TOC  Options  section
       can  also be applied. The table of contents is generated	via XSLT which
       means that it can be styled to look however you want it to look.	To get
       an  idea	 of  how  to do	this you can dump the default xslt document by
       supplying the --dump-default-toc-xsl, and the outline it	 works	on  by
       supplying --dump-outline, see the Outline Options section.

Description
       Converts	 one or	more HTML pages	into a PDF document, using wkhtmltopdf
       patched qt.

Global Options
	   --collate
	      Collate when printing multiple copies
	   --no-collate
	      Do not collate when printing multiple copies
	   --cookie-jar	_path_
	      Read and write cookies from and to the supplied cookie jar file
	   --copies _number_
	      Number of	copies to print	into the pdf file
       -d, --dpi _dpi_
	      Change the dpi explicitly	(this has no effect on X11 based  sys-
	      tems)
       -H, --extended-help
	      Display  more  extensive	help,  detailing  less	common command
	      switches
       -g, --grayscale
	      PDF will be generated in grayscale
       -h, --help
	      Display help
	   --htmldoc
	      Output program html help
	   --image-dpi _integer_
	      When embedding images scale them down to this dpi
	   --image-quality _integer_
	      When jpeg	compressing images use this quality
	   --license
	      Output license information and exit
	   --log-level _level_
	      Set log level to:	none, error, warn or info
       -l, --lowquality
	      Generates	lower quality pdf/ps. Useful to	shrink the result doc-
	      ument space
	   --manpage
	      Output program man page
       -B, --margin-bottom _unitreal_
	      Set the page bottom margin
       -L, --margin-left _unitreal_
	      Set the page left	margin
       -R, --margin-right _unitreal_
	      Set the page right margin
       -T, --margin-top	_unitreal_
	      Set the page top margin
       -O, --orientation _orientation_
	      Set orientation to Landscape or Portrait
	   --page-height _unitreal_
	      Page height
       -s, --page-size _Size_
	      Set paper	size to: A4, Letter, etc.
	   --page-width	_unitreal_
	      Page width
	   --no-pdf-compression
	      Do not use lossless compression on pdf objects
       -q, --quiet
	      Be less verbose, maintained for backwards	compatibility; Same as
	      using --log-level	none
	   --read-args-from-stdin
	      Read command line	arguments from stdin
	   --readme
	      Output program readme
	   --title _text_
	      The title	of the generated pdf file (The title of	the first doc-
	      ument is used if not specified)
	   --use-xserver
	      Use  the	X  server (some	plugins	and other stuff	might not work
	      without X11)
       -V, --version
	      Output version information and exit

Outline	Options
	   --dump-default-toc-xsl
	      Dump the default TOC xsl style sheet to stdout
	   --dump-outline _file_
	      Dump the outline to a file
	   --outline
	      Put an outline into the pdf
	   --no-outline
	      Do not put an outline into the pdf
	   --outline-depth _level_
	      Set the depth of the outline

Page Options
	   --allow _path_
	      Allow the	file or	files from the specified folder	to  be	loaded
	      (repeatable)
	   --background
	      Do print background
	   --no-background
	      Do not print background
	   --bypass-proxy-for _value_
	      Bypass proxy for host (repeatable)
	   --cache-dir _path_
	      Web cache	directory
	   --checkbox-checked-svg _path_
	      Use this SVG file	when rendering checked checkboxes
	   --checkbox-svg _path_
	      Use this SVG file	when rendering unchecked checkboxes
	   --cookie _name_ _value_
	      Set  an  additional cookie (repeatable), value should be url en-
	      coded.
	   --custom-header _name_ _value_
	      Set an additional	HTTP header (repeatable)
	   --custom-header-propagation
	      Add HTTP headers specified by --custom-header for	each  resource
	      request.
	   --no-custom-header-propagation
	      Do  not  add  HTTP headers specified by --custom-header for each
	      resource request.
	   --debug-javascript
	      Show javascript debugging	output
	   --no-debug-javascript
	      Do not show javascript debugging output
	   --default-header
	      Add a default header, with the name of the page to the left, and
	      the   page   number   to	 the   right,	this   is  short  for:
	      --header-left='[webpage]'	--header-right='[page]/[toPage]' --top
	      2cm --header-line
	   --encoding _encoding_
	      Set the default text encoding, for input
	   --disable-external-links
	      Do not make links	to remote web pages
	   --enable-external-links
	      Make links to remote web pages
	   --disable-forms
	      Do not turn HTML form fields into	pdf form fields
	   --enable-forms
	      Turn HTML	form fields into pdf form fields
	   --images
	      Do load or print images
	   --no-images
	      Do not load or print images
	   --disable-internal-links
	      Do not make local	links
	   --enable-internal-links
	      Make local links
       -n, --disable-javascript
	      Do not allow web pages to	run javascript
	   --enable-javascript
	      Do allow web pages to run	javascript
	   --javascript-delay _msec_
	      Wait some	milliseconds for javascript finish
	   --keep-relative-links
	      Keep relative external links as relative external	links
	   --load-error-handling _handler_
	      Specify  how to handle pages that	fail to	load: abort, ignore or
	      skip
	   --load-media-error-handling _handler_
	      Specify how to handle media files	that fail to load: abort,  ig-
	      nore or skip
	   --disable-local-file-access
	      Do not allowed conversion	of a local file	to read	in other local
	      files, unless explicitly allowed with --allow
	   --enable-local-file-access
	      Allowed conversion of a local file to read in other local	files.
	   --minimum-font-size _int_
	      Minimum font size
	   --exclude-from-outline
	      Do not include the page in the table of contents and outlines
	   --include-in-outline
	      Include the page in the table of contents	and outlines
	   --page-offset _offset_
	      Set the starting page number
	   --password _password_
	      HTTP Authentication password
	   --disable-plugins
	      Disable installed	plugins
	   --enable-plugins
	      Enable installed plugins (plugins	will likely not	work)
	   --post _name_ _value_
	      Add an additional	post field (repeatable)
	   --post-file _name_ _path_
	      Post an additional file (repeatable)
	   --print-media-type
	      Use print	media-type instead of screen
	   --no-print-media-type
	      Do not use print media-type instead of screen
       -p, --proxy _proxy_
	      Use a proxy
	   --proxy-hostname-lookup
	      Use the proxy for	resolving hostnames
	   --radiobutton-checked-svg _path_
	      Use this SVG file	when rendering checked radiobuttons
	   --radiobutton-svg _path_
	      Use this SVG file	when rendering unchecked radiobuttons
	   --resolve-relative-links
	      Resolve relative external	links into absolute links
	   --run-script	_js_
	      Run this additional javascript after the page  is	 done  loading
	      (repeatable)
	   --disable-smart-shrinking
	      Disable  the  intelligent	shrinking strategy used	by WebKit that
	      makes the	pixel/dpi ratio	non-constant
	   --enable-smart-shrinking
	      Enable the intelligent shrinking strategy	used  by  WebKit  that
	      makes the	pixel/dpi ratio	non-constant
	   --ssl-crt-path _path_
	      Path  to	the  ssl client	cert public key	in OpenSSL PEM format,
	      optionally followed by intermediate ca and trusted certs
	   --ssl-key-password _password_
	      Password to ssl client cert private key
	   --ssl-key-path _path_
	      Path to ssl client cert private key in OpenSSL PEM format
	   --stop-slow-scripts
	      Stop slow	running	javascripts
	   --no-stop-slow-scripts
	      Do not Stop slow running javascripts
	   --disable-toc-back-links
	      Do not link from section header to toc
	   --enable-toc-back-links
	      Link from	section	header to toc
	   --user-style-sheet _path_
	      Specify a	user style sheet, to load with every page
	   --username _username_
	      HTTP Authentication username
	   --viewport-size __
	      Set viewport size	if you have custom scrollbars or css attribute
	      overflow to emulate window size
	   --window-status _windowStatus_
	      Wait  until window.status	is equal to this string	before render-
	      ing page
	   --zoom _float_
	      Use this zoom factor

Headers	And Footer Options
	   --footer-center _text_
	      Centered footer text
	   --footer-font-name _name_
	      Set footer font name
	   --footer-font-size _size_
	      Set footer font size
	   --footer-html _url_
	      Adds a html footer
	   --footer-left _text_
	      Left aligned footer text
	   --footer-line
	      Display line above the footer
	   --no-footer-line
	      Do not display line above	the footer
	   --footer-right _text_
	      Right aligned footer text
	   --footer-spacing _real_
	      Spacing between footer and content in mm
	   --header-center _text_
	      Centered header text
	   --header-font-name _name_
	      Set header font name
	   --header-font-size _size_
	      Set header font size
	   --header-html _url_
	      Adds a html header
	   --header-left _text_
	      Left aligned header text
	   --header-line
	      Display line below the header
	   --no-header-line
	      Do not display line below	the header
	   --header-right _text_
	      Right aligned header text
	   --header-spacing _real_
	      Spacing between header and content in mm
	   --replace _name_ _value_
	      Replace [name] with value	in header and footer (repeatable)

TOC Options
	   --disable-dotted-lines
	      Do not use dotted	lines in the toc
	   --toc-header-text _text_
	      The header text of the toc
	   --toc-level-indentation _width_
	      For each level of	headings in the	toc indent by this length
	   --disable-toc-links
	      Do not link from toc to sections
	   --toc-text-size-shrink _real_
	      For each level of	headings in the	toc the	font is	scaled by this
	      factor
	   --xsl-style-sheet _file_
	      Use  the supplied	xsl style sheet	for printing the table of con-
	      tents

Specifying A Proxy
       By default proxy	information will be read from  the  environment	 vari-
       ables: proxy, all_proxy and http_proxy, proxy options can also by spec-
       ified with the -p switch

	 <type>	:= "http://" | "socks5://"
	 <serif> := <username> (":" <password>)? "@"
	 <proxy> := "None" | <type>? <string>? <host> (":" <port>)?

       Here are	some examples (In case you are unfamiliar with the BNF):

	 http://user:password@myproxyserver:8080
	 socks5://myproxyserver
	 None

Footers	And Headers
       Headers and footers can be added	to the document	by the --header-*  and
       --footer*  arguments  respectively.   In	 header	and footer text	string
       supplied	to e.g.	--header-left, the following variables will be substi-
       tuted.

	  *  [page]	   Replaced by the number of the pages currently being
       printed
	  * [frompage]	 Replaced by the  number  of  the  first  page	to  be
       printed
	  * [topage]	 Replaced by the number	of the last page to be printed
	  * [webpage]	 Replaced by the URL of	the page being printed
	  * [section]	 Replaced by the name of the current section
	  * [subsection] Replaced by the name of the current subsection
	  * [date]	 Replaced by the current date in system	local format
	  *  [isodate]	   Replaced  by	 the current date in ISO 8601 extended
       format
	  * [time]	 Replaced by the current time in system	local format
	  * [title]	 Replaced by the title of the of the current page  ob-
       ject
	  * [doctitle]	 Replaced by the title of the output document
	  *  [sitepage]	   Replaced  by	 the number of the page	in the current
       site being converted
	  * [sitepages]	 Replaced by the number	of pages in the	 current  site
       being converted

       As an example specifying	--header-right "Page [page] of [topage]", will
       result in the text "Page	x of y"	where x	is the number of  the  current
       page  and y is the number of the	last page, to appear in	the upper left
       corner in the document.

       Headers and footers can also be supplied	with HTML documents. As	an ex-
       ample  one could	specify	--header-html header.html, and use the follow-
       ing content in header.html:

	 <!DOCTYPE html>
	 <html><head><script>
	 function subst() {
	     var vars =	{};
	     var   query_strings_from_url   =	 document.location.search.sub-
       string(1).split('&');
	     for (var query_string in query_strings_from_url) {
		 if (query_strings_from_url.hasOwnProperty(query_string)) {
		     var		       temp_var			     =
       query_strings_from_url[query_string].split('=', 2);
		     vars[temp_var[0]] = decodeURI(temp_var[1]);
		 }
	     }
	     var css_selector_classes =	['page', 'frompage',  'topage',	 'web-
       page',  'section',  'subsection',  'date',  'isodate', 'time', 'title',
       'doctitle', 'sitepage', 'sitepages'];
	     for (var css_class	in css_selector_classes) {
		 if (css_selector_classes.hasOwnProperty(css_class)) {
		     var element =  document.getElementsByClassName(css_selec-
       tor_classes[css_class]);
		     for (var j	= 0; j < element.length; ++j) {
			 element[j].textContent	       =       vars[css_selec-
       tor_classes[css_class]];
		     }
		 }
	     }
	 }
	 </script></head><body style="border:0;	margin:	0;" onload="subst()">
	 <table	style="border-bottom: 1px solid	black; width: 100%">
	   <tr>
	     <td class="section"></td>
	     <td style="text-align:right">
	       Page <span class="page"></span> of <span	class="topage"></span>
	     </td>
	   </tr>
	 </table>
	 </body></html>

       As can be seen  from  the  example,  the	 arguments  are	 sent  to  the
       header/footer html documents in get fashion.

Outlines
       Wkhtmltopdf  with patched qt has	support	for PDF	outlines also known as
       book marks, this	can be enabled by specifying the --outline switch. The
       outlines	 are generated based on	the <h?> tags, for a in-depth descrip-
       tion of how this	is done	see the	Table Of Contents section.

       The outline tree	can sometimes be very deep, if	the  <h?>  tags	 where
       spread  to  generous  in	the HTML document.  The	--outline-depth	switch
       can be used to bound this.

Table Of Contents
       A table of contents can be added	to the document	by adding a toc	object
       to the command line. For	example:

	 wkhtmltopdf	 toc	https://qt-project.org/doc/qt-4.8/qstring.html
       qstring.pdf

       The table of contents is	generated based	on the H  tags	in  the	 input
       documents.  First  a XML	document is generated, then it is converted to
       HTML using XSLT.

       The generated XML document can be viewed	by dumping it to a file	 using
       the --dump-outline switch. For example:

	 wkhtmltopdf		       --dump-outline		       toc.xml
       https://qt-project.org/doc/qt-4.8/qstring.html qstring.pdf

       The XSLT	document can be	specified using	the --xsl-style-sheet  switch.
       For example:

	 wkhtmltopdf	       toc	     --xsl-style-sheet		my.xsl
       https://qt-project.org/doc/qt-4.8/qstring.html qstring.pdf

       The --dump-default-toc-xsl switch can be	used to	dump the default  XSLT
       style  sheet to stdout. This is a good start for	writing	your own style
       sheet

	 wkhtmltopdf --dump-default-toc-xsl

       The XML document	is in the  namespace  "http://wkhtmltopdf.org/outline"
       it  has	a root node called "outline" which contains a number of	"item"
       nodes. An item can contain any number of	item. These  are  the  outline
       subsections  to	the  section  the item represents. A item node has the
       following attributes:

	* "title" the name of the section.
	* "page" the page number the section occurs on.
	* "link" a URL that links to the section.
	* "backLink" the name of the anchor the	section	will link back to.

       The remaining TOC options only affect the default style sheet  so  they
       will not	work when specifying a custom style sheet.

Page sizes
       The  default page size of the rendered document is A4, but by using the
       --page-size option this can be changed to almost	 anything  else,  such
       as:  A3,	 Letter	 and  Legal.  For a full list of supported pages sizes
       please see  <https://qt-project.org/doc/qt-4.8/qprinter.html#PaperSize-
       enum>.

       For  a  more  fine grained control over the page	size the --page-height
       and --page-width	options	may be used

Reading	arguments from stdin
       If you need to convert a	lot of pages in	a batch,  and  you  feel  that
       wkhtmltopdf  is	a  bit	too  slow  to  start  up,  then	you should try
       --read-args-from-stdin,

       When --read-args-from-stdin each	line of	input sent to  wkhtmltopdf  on
       stdin  will act as a separate invocation	of wkhtmltopdf,	with the argu-
       ments specified on the given line combined with the arguments given  to
       wkhtmltopdf

       For example one could do	the following:

	 echo  "https://qt-project.org/doc/qt-4.8/qapplication.html  qapplica-
       tion.pdf" >> cmds
	 echo  "cover  google.com  https://en.wikipedia.org/wiki/Qt_(software)
       qt.pdf" >> cmds
	 wkhtmltopdf --read-args-from-stdin --book < cmds

Page Breaking
       The  current  page  breaking  algorithm of WebKit leaves	much to	be de-
       sired. Basically	WebKit will render everything into one long page,  and
       then  cut  it up	into pages. This means that if you have	two columns of
       text where one is vertically shifted by half a line. Then  WebKit  will
       cut  a  line  into  to pieces display the top half on one page. And the
       bottom half on another page. It will also break image in	two and	so on.
       If  you	are  using  the	 patched  version  of  QT  you can use the CSS
       page-break-inside property to remedy this somewhat. There  is  no  easy
       solution	to this	problem, until this is solved try organizing your HTML
       documents such that it contains many lines on which pages  can  be  cut
       cleanly.

Contact
       If  you	experience  bugs  or want to request new features please visit
       <https://wkhtmltopdf.org/support.html>

Authors
	 Jakob Truelsen		     <antialize@gmail.com>
	 Ashish	Kulkarni	     <ashish@kulkarni.dev>
	 Jan Habermann		     <jan@habermann24.com>
	 Pablo Ruiz GarcAa	     <pablo.ruiz@gmail.com>
	 Trevor	North		     <trevor@blubolt.com>
	 Nate Pinchot		     <nate.pinchot@gmail.com>
	 pussbb			     <pussbb@gmail.com>
	 Aaron Stone		     <aaron@serendipity.cx>
	 Patrick Widauer	     @a-ctor
	 Peter van der Tak	     <pta@ibuildgreen.eu>
	 Benjamin Sinkula	     <bsinky@gmail.com>
	 Kasper	F. Brandt	     <poizan@poizan.dk>
	 Michael Nitze		     <michael.nitze@online.de>
	 Rok Dvojmoc		     <rok.dvojmoc@gmail.com>
	 theirix		     <theirix@gmail.com>
	 Tomsgu			     <tomasjakll@gmail.com>
	 Artem Butusov		     <art.sormy@gmail.com>
	 Christian Sciberras	     <uuf6429@gmail.com>
	 Daniel	M. Lambea	     <dmlambea@gmail.com>
	 Douglas Bagnall	     <douglas@paradise.net.nz>
	 peterrehm		     <peter.rehm@renvest.de>
	 Renan GonA<section>alves	      <renan.saddam@gmail.com>
	 Ruslan	Grabovoy	     <kudgo.test@gmail.com>
	 Sander	Kleykens	     <sander.kleykens@avnu.be>
	 Adam Thorsen		     <adam.thorsen@gmail.com>
	 Albin Kerouanton	     <albin.kerouanton@knplabs.com>
	 Alejandro Dubrovsky	     <alito@organicrobot.com>
	 Arthur	Cinader		     @acinader
	 Benoit	Garret		     <benoit.garret@gmail.com>
	 Bill Kuker		     <bkuker@billkuker.com>
	 cptjazz		     <alexander@jesner.eu>
	 daigot			     <daigot@rayze.com>
	 Destan	Sarpkaya	     @destan
	 Duncan	Smart		     <duncan.smart@gmail.com>
	 Emil Lerch		     <emil@lerch.org>
	 Erik Hyrkas		     <erik.hyrkas@thomsonreuters.com>
	 Erling	Linde		     <erlingwl@gmail.com>
	 FA!bio	C. Barrionuevo da Luz <bnafta@gmail.com>
	 Fr33m1nd		     <lukion@gmx.de>
	 Frank Groeneveld	     <frank@frankgroeneveld.nl>
	 Immanuel HAxussermann	      <haeussermann@gmail.com>
	 Jake Petroules		     <jake.petroules@petroules.com>
	 James Macdonald	     <james@kingfisher-systems.co.uk>
	 Jason Smith		     <JasonParallel@gmail.com>
	 John Muccigrosso	     @Jmuccigr
	 Julien	Le Goff		     <julego@gmail.com>
	 Kay Lukas		     <kay.lukas@gmail.com>
	 Kurt Revis		     <krevis@snoize.com>
	 laura			     @holamon
	 Marc Laporte		     <marc@laporte.name>
	 Matthew M. Boedicker	     <matthewm@boedicker.org>
	 Matthieu Bontemps	     <matthieu.bontemps@gmail.com>
	 Max Sikstrom		     <max.sikstrom@op5.com>
	 Nolan Neustaeter	     <github@noolan.ca>
	 Oleg Kostyuk		     <cub.uanic@gmail.com>
	 Pankaj	Jangid		     <pankaj.jangid@gmail.com>
	 robinbetts		     <robinbetts@yahoo.com>
	 Sem			     <spam@esemi.ru>
	 Stefan	Weil		     <sw@weilnetz.de>
	 Stephen Kennedy	     <sk4425@gmail.com>
	 Steve Shreeve		     <steve.shreeve@gmail.com>
	 Sven Nierlein		     <sven@nierlein.org>
	 Tobin Juday		     <tobinibot@gmail.com>
	 Todd Fisher		     <todd.fisher@gmail.com>
	 DhDh3/4NNDh<degree>Dh'Dh,Dh1/2	      DhDh<degree>Dh1/4NDh1/2Dh3/4Dh^2
       <maxmight@gmail.com>
	 Emmanuel Bouthenot	     <kolter@openics.org>
	 Rami			     @icnocop
	 Khodeir-hubdoc		     @Khodeir-hubdoc
	 Jonathan Jefferies	     @jjok
	 Joe Ayers		     <joseph.ayers@crunchydata.com>
	 Jeffrey Cafferata	     <jeffrey@jcid.nl>
	 rainabba
	 Mehdi Abbad
	 Lyes Amazouz
	 Pascal	Bach
	 MA!rio	Silva

			       2009 February 23			WKHTMLTOPDF(1)

Name | Synopsis | Document objects | Description | Global Options | Outline Options | Page Options | Headers And Footer Options | TOC Options | Specifying A Proxy | Footers And Headers | Outlines | Table Of Contents | Page sizes | Reading arguments from stdin | Page Breaking | Contact | Authors

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=wkhtmltopdf&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help