From The Command-line

The PDF plugin can be called to execute from the command-line without any additional configurations. Like the other plugins, to run the PDF plugin, you use:

  mvn pdf:pdf

where the first pdf refers to the plugin's alias, and the second pdf refers to a plugin goal.

By default, the pdf will be generated in target/pdf/ directory.

Notes:

1. By default, the PDF plugin generates a PDF document which aggregates all your site documents. If you want to generate each site document individually, you need to add -Daggregate=false in the command line.
2. By default, the PDF plugin uses the FOP implementation. The plugin also supports the iText implementation, you just need to add -Dimplementation=itext in the command line.

As Part Of Your Build Process

The PDF plugin can be put into a project's pom.xml so that it gets executed everytime the project is built. Below is a sample configuration (to put into the list of <plugins> in the <build> section of your pom.xml) for running the PDF plugin in the site phase everytime the project is built:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-pdf-plugin</artifactId>
  <executions>
    <execution>
      <id>pdf</id>
      <phase>site</phase>
      <goals>
        <goal>pdf</goal>
      </goals>
      <configuration>
        <outputDirectory>${project.reporting.outputDirectory}</outputDirectory>
        <includeReports>false</includeReports>
      </configuration>
    </execution>
  </executions>
</plugin>

Note: In this case, the pdf plugin is coupled with the Maven Site plugin to generate both site documentation and pdfs into the default output site directory, i.e. target/site. You just need to call mvn site.

Document Descriptor

By default, the pdf plugin processes all source files as specified in the site-plugins's site.xml. You can customize which files to include in which order by using a document descriptor (by default src/site/pdf.xml). An example is given below:

<document xmlns="http://maven.apache.org/DOCUMENT/1.0.1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/DOCUMENT/1.0.1 http://maven.apache.org/xsd/document-1.0.1.xsd"
  outputName="maven-pdf-plugin">

  <meta>
    <title>Maven PDF Plugin</title>
    <author>The Apache Maven Project</author>
  </meta>

  <toc name="Table of Contents">
    <item name="Introduction" ref="index.apt"/>
    <item name="Usage" ref="usage.apt.vm"/>
    <item name="Filtering Document Descriptor" ref="examples/filtering.apt"/>
    <item name="Configuring Reports" ref="/examples/configuring-reports.xml.vm"/>
    <item name="Limitations" ref="limitations.apt"/>
    <item name="FAQ" ref="faq.fml"/>
  </toc>

  <cover>
    <coverTitle>${project.name}</coverTitle>
    <coverSubTitle>v. ${project.version}</coverSubTitle>
    <coverType>User Guide</coverType>
    <projectName>${project.name}</projectName>
    <projectLogo>http://maven.apache.org/images/maventxt_logo_200.gif</projectLogo>
    <companyName>The Apache Software Foundation</companyName>
    <companyLogo>http://www.apache.org/images/asf_logo_wide.png</companyLogo>
  </cover>
</document>

The meta information is only used for the pdf cover page if no cover element is given. The toc generates a Table of Contents and specifies the order of files to include in the pdf. For a complete description of the file format, see the Document Model Reference.

Notes:

1. Only a few of document metadatas are used by the Fo/iText sinks like author, confidential, date and title.
2. The document descriptor supports filtering as described in the filtering example.

Internationalization

The PDF plugin is able to generate internationalized pdfs, similar to the site creation.

To enable multiple locales, add a configuration similar to the following to your POM:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-pdf-plugin</artifactId>
        <version>1.5.1</version>
        <configuration>
          <locales>en,fr</locales>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>

This will generate two pdfs, one English and one French. Like the site plugin, if en is your current locale, then it will be generated at the root of the site, with a copy of the French translation of the site in the fr/ subdirectory.

The following is a complete internationalized directory layout for site and pdf plugins:

+- src/
   +- site/
      +- apt/
      |  +- index.apt     (Default version)
      |
      +- fr/
      |  +- apt/
      |     +- index.apt  (French version)
      |
      +- site.xml         (Default site descriptor)
      +- site_fr.xml      (French site descriptor)
      +- pdf.xml          (Default pdf descriptor)
      +- pdf_fr.xml       (French pdf descriptor)

Specific FOP Configuration Properties

All the layout properties that are used for the pdf conversion using the FOP implementation are read from a default configuration file. The properties in this file may be overridden by using a custom configuration file pdf-config.xml located in src/site/resources/.

The format of this file has to be exactly the same as the original default configuration file. However, you only need to specify the properties that you want to override, e.g. to change the font size of pre-formatted text, you could use:

<xsl:stylesheet
  version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:fo="http://www.w3.org/1999/XSL/Format">

  <xsl:attribute-set name="body.pre" use-attribute-sets="base.pre.style">
    <xsl:attribute name="font-size">8pt</xsl:attribute>
  </xsl:attribute-set>

</xsl:stylesheet>