Extension:Pdf Export

From MediaWiki.org
Jump to navigation Jump to search
The Wikimedia Foundation was working on a newer PDF rendering functionality that was to be supported out of the box. A current approach is the ElectronPdfService extension developed by Wikimedia Germany.
Various panic comments:
  • works fine with MW 1.21 and MW 1.23 with these changes: http://www.mediawiki.org/wiki/Extension_talk:Pdf_Export#MWlib_issues_28541 with htmldoc
  • MW 1.23: as by 2014-12-13 the extension is working out of the box from Git master branch. The snapshot 'PdfExport-REL1_23-b1fcfeb.tar.gz' however seems not to be working.
  • MW 1.24: as of 2015-01-06 The snapshot 'PdfExport-REL1_24-7b48868.tar.gz' is working.
  • Working 3.2.0 with MW 1.25 and mpdf.
  • Actual PdfExport-REL1_27 does not work with back-ends specified below. Try with Dompdf as it is mentioned here. It works but results are not very good...
MediaWiki extensions manualManual:Extensions
Crystal Clear action run.svg
Pdf Export

Release status:Extension status unmaintained

ImplementationTemplate:Extension#type Special page, Data extraction
DescriptionTemplate:Extension#description Converts current page to PDF and sends to browser
Author(s)Template:Extension#username Thomas Hempel (Thempel Talk)
Christian Neubauer (Cneubauer Talk)
Andreas Hagmann (AhTalk)
Craig Oakes (w1BBoRTalk)
Latest versionTemplate:Extension#version 3.0.1 (2012-11-02)
Database changesTemplate:Extension#needs-updatephp No
LicenseTemplate:Extension#license GNU General Public License 2.0 or later
Download MediaWiki 1.6.7 - 1.16: see here
MediaWiki 1.15+:
ExampleTemplate:Extension#example Syncleus Wiki Example

Translate the Pdf Export extension if it is available at translatewiki.net

Check usage and version matrix.

The Pdf Export extension lets you view wiki pages as PDF. It has two modes:

  1. For any given page, it acts like the SpecialCite.php extension and provides a link in the toolbox to view that page as PDF.
  2. If you invoke the Pdf Export special page directly, it lets you select a group of wiki pages and output them as a single PDF document. In that view you can also choose orientation (landscape vs portrait) and paper size.

The extension originally worked with the open source htmldoc package. As of version 2.5, it supports a variety of backends including HTMLDoc, DomPdf, MWlib, MPdf, and PrinceXML. It works by rendering the current page without all the navigation stuff and passing that HTML to the backend system for conversion to PDF.

The current version works with recent versions of MediaWiki. The older version of the extension may work with versions as far back as 1.6.7.


Install one of the backends (on Debian based systems such as Ubuntu or Mepis use: apt-get install htmldoc for example). Windows binaries for HTMLDoc can be found here (v1.8.27).

Add the following to your MediaWiki installation's LocalSettings.php.

Note: You only need to add one of the five optional backend PDF tools
require_once "$IP/extensions/PdfExport/PdfExport.php" ;

## Define only one of the following backends:

# PrinceXML
$wgPdfExportPrincePath = '/usr/local/bin/prince'; // Path to the PrinceXML binary
$wgPdfExportPrincePhpInterface = $IP . '/extensions/PdfExport/prince.php'; // Path to the prince.php file from the prince website.

# MWLib
$wgPdfExportMwLibPath = '/usr/local/bin/mw-render'; // Path to the mw-render binary

# MPdf
$wgPdfExportMPdf = $IP . '/extensions/PdfExport/mpdf/mpdf.php'; // Path to the main mPDF.php file

$wgPdfExportHtmlDocPath = '/usr/bin/htmldoc';

You may also define a background image which will be printed to every page of the resulting PDF by setting the corresponding constant (note that this only works for the htmldoc backend):

$wgPdfExportBackground = "path/to/the/background-image/image.jpg";

You can also set a variable to control if the PDF opens in the browser window or is downloaded as an attachment. To make the PDF download as an attachment set:

$wgPdfExportAttach = true;
The possibility to provide a different filename other than the pagename of the page to be printed requires this parameter to be set to "true".


The paper size for the PDF to be created is set with the "MediaWiki:Pdf_size_default" system message. Available sizes are "letter" and "A4".

Version history[edit]

version history


  • Fix the special page. YesY Done
  • Add a "nopdf" class that can be added to elements to prevent them from showing up in the PDF output.
  • Test compatibility with older and newer versions of MediaWiki.
    • Did basic testing with mPDF on 1.15.5, 1.16.5, 1.17.5, 1.18.4, and 1.19.1. Each successfully generated a PDF document from the default main page.
  • Make sure all the special page options work with all backends (i.e. password protection, font family selection, etc).
  • Add the ability to insert a header and footer into the PDF.
  • Add a global variable to enable or disable the "advanced" options on the special page (like password protection).
  • Add the ability to specify page breaks in the PDF output.

See also[edit]

  • Extension:Collection - allows to build collections from a number of pages. Collections can be edited, persisted and retrieved as PDF.
  • Extension:Pdf Book - composes categories of articles into a book in PDF format, also uses HTMLDOC.

Benefits/Drawbacks of the Backends[edit]


HTMLDoc is very simple to install and use, especially on Linux based systems. It supports only very basic CSS statements though so some layout and style options won't show up in the final PDF. For example, HTMLDoc doesn't support colored links or floated images.


MWLib was developed specifically for MediaWiki and was used years ago on Wikipedia to generate PDFs. It does a direct translation of wikitext to PDF. It handles most style and layout options very well. One major issue is it doesn't support colored links. All links show up as black and white.

Also, if you are running Semantic MediaWiki (SMW), your inline queries will not be run by MWLib, resulting in no output where you would be expecting results in tables or lists.


MPdf seems to be the only backend to support UTF-8 character sets and TrueType fonts. It should be considered if you are using a non-English language wiki. It supports most styles and layouts although in testing, it had problems with floating of tables (in infoboxes for example). It also doesn't handle thumbnailed images perfectly.


PrinceXML is a commercial tool. It handles most (all?) of CSS 2.1 and some of CSS 3.0. It can handle fairly complex style and layout. Like DomPdf, it seems to have trouble displaying floated images with text wrapped around them. Prince requires well-formed XHTML so it requires that tidy be installed.