wiki:TracWikiPrintPlugin

Version 61 (modified by Cinc-th, 3 years ago) (diff)

Added install instructions for dependency pdfkit

Make Trac wiki pages printable

Description

This plugin allows you to export to PDF (book or article format) or printable HTML format (page contents without Trac headers/footers) allowing easy printing. PDF export is based on wkhtmltopdf.

Older versions up to V3.0.0 used xhtml2pdf for generating PDF files. While having the advantage of being a pure Python solution it was abandoned because the output quality of wkhtmltopdf is way better. For these unsupported older releases see WikiPrintXhtml2pdf.

Example of an exported wiki page

Slightly smaller screenhot of a PDF page so Trac may display it.

Key features:

  • Administration page for default settings.
  • Customizable footers for PDF.
  • Customizable front page for PDF book format.
  • Automatic creation of Table of Contents for PDF books.
  • The style of the resulting PDF or HTML can be fully customized using CSS.
  • Different page sizes.
  • PDF "print dialog" for altering settings prior to PDF file creation.
  • Makro to specify contents and format of PDF Books with export feature.

The plugin is seamlessly integrated in the Trac user interface by adding items to the Download in other formats section of each wiki page.

See also

Supported Trac releases

Trac 1.4 and 1.6 are fully supported.

For older releases use TracWikiPrintPlugin V3.x.x or older. See WikiPrintXhtml2pdf for more information.

License

Releases up to V3.x.x were licensed as GPL.

With V4.0.0 the plugin was rewritten from scratch and is now BSD licensed.

Bugs/Feature Requests

Existing bugs and feature requests for TracWikiPrintPlugin are here.

If you have any issues, create a new ticket.

defect

33 / 43

enhancement

7 / 19

task

7 / 8

Download

Download the zipped source from here.

Source

You can check out TracWikiPrintPlugin from here using Subversion, or browse the source with Trac.

The plugin is also available on PyPi.

Installation

The plugin depends on pdfkit. When installing with pip the library pdfkit is automatically fetched. It is also possible to install the library as an egg using Tracs plugin admin page.

To install the plugin from trunk:

$ pip install https://trac-hacks.org/svn/tracwikiprintplugin/trunk

To install the older V3.0.0 release:

$ pip install https://trac-hacks.org/svn/tracwikiprintplugin/tags/V3.0.0

Install wkhtmltopdf.

Note: wkhtmltopdf must be in your path or more precisely in the path used by Trac.

Enable the plugin using Tracs plugin administration page or by adding tracpdf.* = enabled in the components section of your trac.ini file:

[components]
...
tracpdf.* = enabled

Configuration

Configuration can be done using the new administration page Page Parameters in section Wikiprint.

The settings can also be specified in trac.ini:

[wikiprint]
# Name of a wiki page used as the cover for a PDF book
coverpage = CoverPageInWiki

# One of the predfined footers to be added to a PDF. Leave empty for
# no footer.
#
# Available footers:
# 1: [page] / [topage]
# 2: {pagename}  -  [page] / [topage]
footertext = [page] / [topage]

# One of the predefined page sizes: A3, A4, A5, B4, B5, B6, Folio, Legal, Letter
pagesize = A4

# Name of a wiki page containing CSS style information.
# A style page must be located below WikiPrint/Styles/
# If left empty Tracs default wiki styles are used.
stylepage = WikiPrint/Styles/StylePage

# Title to be used in the PDF properties. If left empty
# the wiki page name will be used
title = 

# Whether to include a table of content in a PDF book
toc = enabled|disabled

Permissions

Wikiprint defines a new permission:

  • WIKIPRINT_ADMIN: Allow users to access the Page Parameters admin page, and configure wikiprint default settings.

To actually view a wiki page and export it to PDF the user must have WIKI_VIEW permission.

Usage

After the plugin is enabled, a new administration panel will be available under the Wikiprint section, and 4 new download formats will be available in the Download in other formats section at the end of each wiki page:

  • Printable HTML
  • PDF Page
  • PDF Page (custom settings)
  • PDF Book

A new makro PdfBook can be used to create PDF books from any number of wiki pages.

Administration page

The default configuration for page exports may be provided using the Wikiprint administration page. These settings apply when not overriden by the user while exporting a PDF. While most settings are related to PDF files the style page specified here also applies when generating the Printable HTML page.

Example of a PDF book

Screenshot of administration page for PDF parameters.

Printable HTML

The wiki page is stripped from Tracs footer, header and navigation. The resulting page only contains the wiki content.

Styling of the page is according to the style page selected using the administration panel.

PDF Page

PDF Page creates a PDF file out of the wiki page, with no cover page. Styles will be used from the style page defined in the global configuration set with the administration panel.

Table of contents macros in the wiki page like [[PageOutline()]] or others are not stripped from the page.

PDF Page (custom settings)

The wiki page is exported as a PDF file. This is like normal PDF Page export but it is possible to override the global configuration while generating the PDF file. A settings page similar to a "print dialog" is presented to the user before the actual export happens.

Setting parameters for PDF page export

Screenshot of PDF page settings.

PDF Book

This will create a book-like PDF document. While exporting the user is presented with a settings page to specify a cover page and whether a table of contents should be added. Styling may be changed by selecting one of the available style pages. The cover page used for the book may be any wiki page.

Common table of contents macros in the wiki page like [[PageOutline()]] or [[TracGuideToc()]] are removed from each wiki page.

Each book starts with the cover page (if any) directly followed by the table of contents (if enabled).

Example of a PDF book

Screenshot of a PDF book with cover page and table of contents

PdfBook makro

Using the makro it is possible to define PDF books with any number of wiki pages a cover page and table of contents. The configuration specified in the makro may always be overriden by the user while creating the book. This way one may for example change the predefined cover page or omit the table of contents. Note that you can't add or remove pages while creating the book.

The configuration from the makro is rendered to the user and a button added to create the PDF book. Note that only one PdfBook makro on a wiki page is supported.

The makro must be specified in WikiProcessors syntax:

{{{#!PdfBook
...
}}}

The contents must be formatted like an INI file. The following sections are defined:

  • [parameters]: specify cover page and table of contents
  • [pages]: list of wiki pages to add to the book.
{{{#!PdfBook
[parameters]
# Name of a wiki page to be used as the cover page
cover = CoverPage
# Set to 1 for a table of contents, else set to 0
toc = 1

[pages]
# Names of wiki pages to be added to the PDF book.
WikiStart
WikiFormatting
}}}

Example of PdfBook makro

Screenshot of {{{PdfBook}}} makro

Custom styling

It is possible to use styles different to Tracs default CSS. A wiki page must be created below WikiPrint/Styles/ containing the styles to use.

For example

WikiPrint/Styles/StylePage

The page will automatically be available for selection when creating PDF files and on the administration page.

Recent Changes

18614 by jun66j5 on 2024-01-06 00:22:59
TracWikiPrintPlugin 4.0.0dev: set text/markdown to long_description_content_type in order to fix syntax errors in long_description while uploading dist files
18613 by jun66j5 on 2024-01-05 23:30:16
TracWikiPrintPlugin 4.0.0dev: enable [bdist_wheel] universal option
18612 by jun66j5 on 2024-01-05 23:24:23
TracWikiPrintPlugin 4.0.0dev: fix exception raised when downloading pdf from anonymous users and users with basic authentication, and adapt to pdfkit 1.0.0 (closes #14087)
(more)

Author/Contributors

Author: Cinc-th
Maintainer: Cinc-th
Contributors:

Attachments (8)

Download all attachments as: .zip