Extension:PdfBook
![]() | This extension is incompatible with MediaWiki 1.39 or any later release! You are advised against using this extension on a live site. Volunteer developers are invited to pledge their efforts to updating this extension to make it compatible with MediaWiki 1.39 by replacing the {{Incompatible }} template with {{Incompatible |version=1.39|pledge=~~~~}} . |
![]() | This extension is currently not actively maintained! Although it may still work, any bug reports or feature requests will more than likely be ignored. |
![]() Release status: unmaintained |
|
---|---|
Implementation | Data extraction |
Description | Composes a book from articles in a category and exports as a PDF file |
Author(s) | Aran Dunkley, Igor Absorto |
Latest version | 2.0.5 (2021-07-19) |
MediaWiki | 1.25 - 1.35 |
Database changes | No |
License | GNU General Public License 2.0 or later |
Download | GitLab: |
|
|
The PdfBook extension composes a book from articles in a category and exports as a PDF file.
Overview[edit]
Categories are a good way of organizing many articles which together comprise a kind of book. The sort-keys in the 'articles' categorization statements can be used to ensure that they are ordered properly. This extension allows such categories to be compiled into downloadable PDF files with a table of contents, each article forming the start of a new chapter.
Installation[edit]
- Htmldoc
Htmldoc needs to be installed.
- On Debian based systems such as Ubuntu or Mint use:
apt-get install htmldoc
. - On Windows compile or install HTMLDOC and add HTMLDOC to the PATH. Binaries can be found here (paehl.com).
- On Mac OS X: Downloading from source, using the common "./configure; make; sudo make install" procedure" works if you have those developer tools installed.
Note: HTMLDOC does not have very good UTF-8 support.
- PdfBook
- Download and place the file(s) in a directory called
PdfBook
in yourextensions/
folder. - Add the following code at the bottom of your
LocalSettings.php
:wfLoadExtension( 'PdfBook' );
- Configure as required.
Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Usage[edit]
The PDF creation is initialised by the pdfbook action, so a category can be downloaded as a PDF book directly from a link such as:
http://www.foo.bar/wiki/index.php?title=Category:foo&action=pdfbook
A more generic way of creating the link is to use the "fullurl" parser function and the FULLPAGENAME built in variable as in the following example.
[{{fullurl:{{FULLPAGENAME}}|action=pdfbook}} download this selection of articles as a PDF book]
This link can then be added to a template which can be transcluded into any category or article suitable for downloading as a book. For an example of such a template, see OrganicDesign:Category:I am that, which uses OrganicDesign:Template:Book to display the message and download link.
In order to include this parser function link automatically to every category page, add it to the Mediawiki:Category-article-count page.
This extension also allows books to be generated from non-category pages as well. If the article to be downloaded as a book is not a category, then the extension will extract the titles from article links in a bullet list. The list may be explicitly defined, or may be the result of a query. For an example of this functionality, see Creating a PDF book from a DPL query
Raw HTML output[edit]
You can download the file as a single HTML document by setting format=html in the query-string. Example:
http://www.foo.bar/wiki/index.php?title=Main_Page&action=pdfbook&format=html
Single page exports[edit]
You can export a single article as a one-page PDF by setting format=single in the query-string. Example:
http://www.foo.bar/wiki/index.php?title=Main_Page&action=pdfbook&format=single
Page Breaks[edit]
You can add page breaks into your book by adding <!-- PAGE BREAK -->
into the relevant places in the content articles.
Configuration[edit]
Here are some global variables which affect the operation of the extension. These should be set in your LocalSettings file after the include of the PdfBook.php script. These configuration options can be overridden by the parser function so that they can be set specifically for each book.
Variable | Default value | Meaning |
---|---|---|
$wgPdfBookTab
|
false
|
Whether or not an action tab is wanted for printing to PDF |
$wgPdfBookLeftMargin
|
'1cm'
|
Left page margin |
$wgPdfBookRightMargin
|
'1cm'
|
Right page margin |
$wgPdfBookTopMargin
|
'1cm'
|
Top page margin |
$wgPdfBookBottomMargin
|
'1cm'
|
Bottom page margin |
$wgPdfBookFont
|
'Arial'
|
Default font to use if unspecified in content |
$wgPdfBookFontSize
|
'8'
|
Point size of default font |
$wgPdfBookFontSpacing
|
1
|
Vertical line spacing |
$wgPdfBookLinkColour
|
'217A28'
|
Colour to use when rendering hyperlinks in text |
$wgPdfBookTocLevels
|
'2'
|
Number of outline levels to use when building the table of contents |
$wgPdfBookExclude
|
array()
|
List of article titles which should not be included in the book |
$wgPdfBookHtmlDocPath
|
'/usr/bin/htmldoc'
|
Allows for setting a custom path to HTMLDOC binary |
Bugs and Todo[edit]
Please see the GitLab issue tracker to view or report bugs.
- Note: This extension does not work with MediaWiki 1.32 yet - see issue #4 in GitLab.
- Kindly update the "Usage" section with a step by step guide of how to implement the sidebar link for the vector theme.
- Multibyte characters not working
- Tables are "hardwired" to a standard format currently
- Dynamic per-book parameters not done yet
- If pdfbook is generated from an article containing article links in a bullet list, all articles in the pdf have the title of the first article in the list, not their own.
- Solution: change the line 122 of PdfBook.php to this: "$wgOut->setHTMLTitle( $ttext, true ); # use this so DISPLAYTITLE magic works"
See also[edit]
- PDF export - summary of all PDF export extensions