Single page HTML/PDF output

Paradox can output documentation as a single page HTML or PDF document, by running paradoxSingle and paradoxPdf respectively.

Single page HTML

Paradox will compile each file configured in paradoxRoots as a single page that contains the entire tree that each page contains into the target/paradox/site-single folder. Links between pages are handled in the following way:

• A link to path/to/page.html will be converted to an anchor link, #path/to/page.html, and an anchor will be generated at the start of the page for it to link to.
• Links to anchors, eg path/to/page.html#anchor, will be convert to #path/to/page.html~anchor, with the anchor link updated accordingly.

Header depth is offset by how deep a page is in the navigation tree. So, if a.html has a child page of b.html which has a child page of c.html, then an h1 in c.html will become an h3. This can result in rather deep header nesting, so for header depths greater than 6, a div is generated with a class of h7, h8 and so on.

The table of contents directive is disabled.

sbt configuration options such as paradoxNavigationDepth and paradoxProperties default to the values configured for regular paradox site generation, but can be overridden by scoping them to paradoxSingle, for example:

paradoxNavigationDepth in (Compile, paradoxSingle) := 4

Single page theming

The single page HTML output uses a template called single.st. The default theme includes both css/page.css as well as css/single.css, so sites that use the default theme and provide a custom page.css need to make no changes to have their custom styling picked up. The default css/single.css uses CSS counters to number headings up to a depth of 4.

PDF

Paradox will compile the first file found in paradoxRoots to a file called <artifact-id>.pdf in the target/paradox/pdf folder. It uses wkhtmltopdf to convert a single page HTML site to a PDF, which is able to generate a table of contents including page numbers. Paradox uses Docker to run wkhtmltopdf, so a Docker installation is required.

The same rules as apply to single page HTML generation apply to PDF site generation, however PDF generation uses a different template for generating the site, since css libraries such as foundation can cause problems for wkhtmltopdf, and there’s also no need to include navigation in the PDF due to the table of contents that is generated. The template used is called print.css, and the default theme includes css/page.css, css/single.css and css/print.css, in that order.

As with the single page documentation, the sbt configuration options default to the values for the regular paradox site, and can be overridden by scoping them to paradoxPdf.

Table of contents

wkhtmltopdf generates a structure of the document in XML, by default this is dumped to a file called target/paradox/pdf/main/toc.xml. It then uses an XML stylesheet (XSLT) to convert this to a table of contents page. The stylesheet used can be set using the paradoxPdfTocTemplate setting, it defaults to print-toc.xslt, and the file must be relative to the theme directory. Setting paradoxPdfTocTemplate to None will turn of table of contents generation.

The current site is mounted in the Docker image at /opt/paradoxsite, so to reference static assets such as css files from the template, the path file:///opt/paradoxsite can be used.

The default table of contents can be seen here, and more details can be read in the wkhtmltopdf documentation.

Cover page

The cover page for the PDF is generated by running a template called print-cover.st.

Other options

The arguments passed to wkhtmltopdf can be customized using paradoxPdfArgs. See the wkhtmltopdf documentation for the full range of options available.

The Docker image used to run wkhtmltopdf can be customized using paradoxPdfDockerImage. At time of writing, the build in use is a development build which has been downloaded from here, and is needed due to this issue in 0.12.5.