If you own a MediaWiki-based Wiki and you're looking for a way to transform your pages to PDF files, look no further: the PdbBook extension has (almost) anything you need to do so. It even allows you to transform a whole category into a single PDF - just like the name implies! I personally found it incredibly useful, since I make a good use categories to organize many articles together, hence I can use that extension to conveniently "inflate" them into a kind of book. This extension allows such categories to be compiled into downloadable PDF files, together with a table of contents: each article forming the start of a new chapter; it also supports the sort-keys statements, so that they can be used to ensure that they are ordered properly within the "book".
The only issue I found with this extension was installing it on Windows environments, where I still have some Wikis I have to manage: that's the reason why I wrote this article - hoping that it will help those who'll hit the same problems I had to overcome.
Installation
Start by following the brief guide described in the official PdfBook extension page: as you can read there, you have to install HTMLDOC first, since it's a required prerequisite. If you don't know what HTMLDOC is, read here: in a nutshell, it's a program that convert HTML & Markdown source files into EPUB, HTML, PostScript, or PDF files - licensed under GNU General Public License: we could easily say that the HTMLDOC executable is what will take care of doing all the hard work, being PdfBook not much more than a wrapper for the MediaWiki engine. You can download HTMLDOC from its official GitHub repository.
Once done, you can download, install and configure the PdfBook extension in the following way:
- Download this huge package, containing a whole lot of extension for multiple platforms/frameworks - including PdfBook for MediaWiki.
- Extract the above package into a temporary folder
- Locate the /MediaWiki/PdfBook/ folder, which is the only thing that you need there, and copy it inside your MediaWiki /extensions/ folder.
- Edit the MediaWiki's LocalSettings.php configuration file and add the following line at the end of the wfLoadExtension block:
|
1 2 |
// load the PdfBook extension wfLoadExtension( 'PdfBook' ); |
Additionally, you might want to add one or more of these configuration settings. I personally found very useful the $wgPdfBookTab option, which adds a neat tab specific for PDF output to the UI for all single pages and categories that allows users to generate PDF files with one click.
Troubleshooting
So far so good: if you're running MediaWiki in a Linux environment, that should be enough... As long as your webserver user has write access to /var/tmp/, which is the temporary folder used by HTMLDOC.
In case you're running MediaWiki on Windows, you most likely have to perform the following additional steps:
- Add the HTMLDOC full path in the Windows' PATH environment variable (CPanel > System > Environment Variables), otherwise PdfBook will never work.
- Grant the read & execute permissions to the IUSR and IIS_IUSRS users for the HTMLDOC root folder (and children).
If it doesn't work either - for example, if you're getting a zero-bytes or an invalid PDF file - you might also have to perform the following tweaks (one at a time):
- Copy the libeay32.dll and ssleay32.dll files from your PHP folder to the HTMLDOC root folder.
- Copy the msvcp71.dll file to the HTMLDOC root folder (you can find it from the NET 1.1 runtime - it gets installed in the C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322 folder).
IMPORTANT: Be sure to perform a iisreset at the end of each one of these steps before testing them.
If the problem persist (in my case, it did) you can try to manually edit the /extensions/PdfBook/PdfBook.hooks.php file and comment the following line (line 158 at the time of writing):
|
1 2 |
// Execute the command outputting to the cache file //putenv( "HTMLDOC_NOCGI=1" ); |
This is precisely how I did manage to fix my specific scenario.
That's it for now: happy PDF printing!
