Paradox can output documentation as a single page HTML or PDF document, by running
Single page HTML and PDF output are still experimental. Some features, such as groups, may not be handled properly.
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.htmlwill 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
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
h8 and so on.
The table of contents directive is disabled.
sbt configuration options such as
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
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.
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/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
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
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 cover page for the PDF is generated by running a template called
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.