====== DW2PDF Plugin ====== ---- plugin ---- description: Export DokuWiki content to PDF author : Andreas Gohr and Gerrit Uitslag email : andi@splitbrain.org, klapinklapin@gmail.com type : action, renderer lastupdate : 2023-11-25 compatible : !Greebo, Hogfather, Igor, Jack Jackrum depends : conflicts : similar : pdfex, html2pdf tags : export, pdf downloadurl: https://github.com/splitbrain/dokuwiki-plugin-dw2pdf/tarball/master bugtracker : https://github.com/splitbrain/dokuwiki-plugin-dw2pdf/issues/ sourcerepo : https://github.com/splitbrain/dokuwiki-plugin-dw2pdf donationurl: ---- Previous developer: [[l.micco@tiscali.it|Luigi Micco]] ===== Download and Installation ===== Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually. Only **PHP 7.4 up to PHP 8.1** are supported by dw2pdf plugin. At rather short term support for PHP 7.4 will be dropped. To export (png) images with an alpha channel (used for transparency), you need to install the GD library for PHP. For example on Debian systems: sudo apt-get install php-gd Also see the [[:tips:phpwithgd|PHP with gd]] tips page. ==== Recent Changes ==== {{rss>https://github.com/splitbrain/dokuwiki-plugin-dw2pdf/commits/master.atom date}} ===== Overview ==== The goal of this plugin was to provide a simple, ready-to-go PDF converter that almost faithfully replicates the screen view of your wiki pages (i.e. doesn't convert them to a print-document format like the latex plugin). It also bundles the necessary fonts and libraries (**hence the 48MB size**) so that you should not need to do any configuration to get it up and running as quickly as possible. ===== Features ===== * Uses the [[https://mpdf.github.io|mPDF]] PHP library. * Handles different languages (it bundles the large, but relatively complete Unicode font). * Easy customizing through headers, footers and CSS * Automatic index of bookmarks * Use with the [[plugin:bookcreator|BookCreator]] plugin to create a PDF from only the pages selected. Since July 2017 version 7.0-beta of mPDF library is included, which supports PHP7, but not PHP 5.4 and older. As (temporary) fallback the following old releases could be found: * Since 11 June 2015 version 6.0 of the mPDF library was included. This should significantly improve the styling possibilities. However there could also be regressions. \\ Release based at previous mPDF 6.0 version -- [[https://github.com/splitbrain/dokuwiki-plugin-dw2pdf/archive/mpdf600.zip|dw2pdf Plugin with mPDF 6.0.0.zip]] (50 MB) * Release based at previous mPDF 5.7.4 version -- [[https://github.com/splitbrain/dokuwiki-plugin-dw2pdf/archive/mpdf574.zip|dw2pdf Plugin with mPDF 5.7.4.zip]] (12 MB) ===== Usage ===== There are three ways to export: * **Export one page**\\ You simply need to call the page with an additional ''do=export_pdf'' URL parameter. This starts the PDF export of the page. Some templates let the plugin extend the [[plugin:dw2pdf:pagetools]] automatically. For other templates you need to implement this yourself to add a button or similar somewhere in your template design. * **Export an entire namespace**\\ There is the URL parameter ''do=export_pdfns'' which let you export a chosen entire namespace as one PDF (e.g. use ''&do=export_pdfns&book_ns=my:namespace&book_title=Mytitle'' (See [[plugin:dw2pdf:configuration|Configuration options]] on how to exclude specific pages). Or create a link with the [[#Syntax|syntax]]). * **Export selection of pages**\\ If you need to select just some pages to export to one PDF, you can use [[plugin:Bookcreator]] plugin, which offers an interface for the dw2pdf plugin. ===== HowTo's===== Please refer to the following pages to learn how to use or support the plugin: * Set [[plugin:dw2pdf:configuration|Configuration options]] via URL or via the Configuration Manager * [[plugin:dw2pdf:pagetool|How to add export button in pagetools/menu's]] * [[plugin:dw2pdf:pdftemplates|Layout and Customize the exported PDF for your (corporate) identity]] * Plugin developers: [[plugin:dw2pdf:exportsupport|How to support export to PDF in your plugin]], including creating your own replacement patterns for use in HTML templates ===== Syntax ===== To create a link in any wiki page to export any namespace, you can use the following syntax: ''%%~~PDFNS>namespace|pdftitle~~%%'' * ''namespace'' is the namespace you want to export * ''pdftitle'' is the title of the generated output PDF * You can add further options (like ''%%&book_order=pagename%%'') by simply appending them to the pdftitle. Handling of [[config:startpages]]: If the page '':start'' doesn't exist, it checks if the page with the name '''' exists and will add to the pdf as well. ===== Issues and Requests ===== Please report issues and requests in the issue tracker:\\ https://github.com/splitbrain/dokuwiki-plugin-dw2pdf/issues/ ==== How to collect more debug info? ==== If you are using the dw2pdf plugin and you don't get the wanted output, than you might investigate the data during its workflow. The dw2pdf plugin uses the HTML code of the print version of an wiki article (which has a leaner styling than the screen version) and converts this code with the mPDF-library to a pdf-file. Some options to investigate with the intermediate results are: - Look at the print preview of an article via the print preview function of your browser - Output the plain html for manually testing or reading. **How-to** output the plain html (just before it is fed into the mPDF library): - Enable the debugging mode of the wiki with the [[config:allowdebug]] setting (see also [[devel:debugging]]) - Add url-parameter to the url used to initiate your pdf-export (copy and modify the link of the button or url you use): * Adding ''&debughtml=text'' displays html as plain text in the browser * Adding ''&debughtml=html'' displays html rendered by the browser See for the debugging options of the mPDF library related to images: [[https://mpdf.github.io/what-else-can-i-do/images.html|images documentation]] of mPDF. ===== Sites using this plugin ===== Feel free to add yours here: * [[http://www.blesk.ca/wiki/|BLËSK User Guide (English)]] * [[http://wiki.fibu-schnittstelle.de|Financial accounting - webshop - interface (German)]] * [[http://wiki.hiorg-server.de/|Handbuch HiOrg-Server (German)]] * [[http://manuals.lacie.com/en/manuals/bladerunner/|LaCie user manuals]] * [[http://mundoaz.com/wiki|Mundoaz - Satellite Decoders (Portuguese)]] * [[http://www.pkuinfo.it|PKUinfo: Informazioni, domande e risposte sulla fenilchetonuria]] * [[http://pe.hillschmidt.de|Prinz Eisenherz - Prince Valiant - Lexikon - Encyclopedia]] * [[http://www.qem.eu/doku/doku.php|QEM srl manuals (Italian)]] * [[http://kantuz.esponde.net/|Wiki Kantuz]] * [[https://webge.fr/dokuwiki|WEBGE wikis (french)]] ===== Other info ===== ==== Linked Images ==== Not all image format variations are successfully embedded in the PDF, even if they are properly displayed in DokuWiki. If you get missing images in your output, try stripping the Alpha channel of your (e.g. PNG) images. * The mPDF library used by this plugin for building the pdf requires the GD library for processing .png images with alpha channels. If using full http links, make sure the permissions are set up for retrieving the image directly (test in a browser). DokuWiki may prevent outside access to images in the data/media directory. ==== Password protection of generated documents ==== To set fixed password for generated documents, edit: ''dokuwiki/lib/plugins/dw2pdf/mpdf/config.php'' (warning: each plugin update overwrites these changes) and add following lines: $this->setUserRights(); $this->SetProtection(array('print','copy', 'modify'),'password','password'); where ''password'' is your password :) (filips) ==== Hyphenation ==== With the following setting in ''style.css'' it is possible to enable automatic hyphenation: body { hyphens: auto; } The hyphenation is of course language dependent. Normally, the wiki login language is used. If the [[translation|translation plugin]] is installed, the language selected here is used for hyphenation when creating the PDF. ==== Rendering Limitations ==== Because the rendering is done on the server side, plugins that rely on the client side to render might not do so correctly in the generated PDF. Example: [[plugin:mermaid]]