You customize the PDF Generator template
style by using CSS. You can also use HTML to modify the cover page and XSLT to apply
advanced structural customizations.
For detailed information on the CSS features supported by the PDF Generator, see the Prince CSS
Reference.
PDF Generator Templating Basics
You can customize the PDF Generator
templates by embedding or importing the CSS code into the code editor.
Tip: We recommend extending the Gray and Color templates with custom CSS rather
than creating a template from scratch.
Embedded style
A CSS code added directly to the PDF GeneratorCSS
tab.
The HTML tab in the right pane enables you to see the
following:
HTML elements rendered from DITA elements
Classes associated with the HTML elements
Remember:You can use the CSS classes and HTML elements as selectors in the CSS code of your template. Keep in mind that HTML elements tend to be more general than CSS classes. For example, styling the li HTML element affects the table of contents, ordered lists, unordered lists, and even task steps.
Tip: If needed, we recommend learning the CSS and HTML basics from the
following resources:
To learn about the CSS features supported by the PDF Generator, see Prince CSS
Reference.
Selecting HTML Elements
In the following example the h1 element (h1
selector) is used to style the chapter-level topic titles.
Chapter-level topic
A topic that is a child of a publication map.
h1 {
color: darkcyan;
font-weight: bold;
}
Selecting HTML Classes
In the following example, the uicontrol class
(.uicontrol selector) is used to style the rendered UI control elements.
.uicontrol {
color: cyan;
font-weight: bold;
}
Gray and Color Templates
The Gray and Color templates are complete and
modular styles that you can leverage to quickly create your own PDF Generator templates.
Tip:The Gray and Color templates differ only in default
colors. You can change the default colors, logo placeholders, and captions at
any point. The template colors are determined in the palette modules.
The Gray and Color templates consist of several
modules that style specific aspects of the document. The CSS code in each module is
thoroughly commented to make the optional customizations easier.
By default, the templates are optimized for screen reading (and not printing).
Because of that, some print-friendly modules are disabled (/* commented-out
*/).
CAUTION: Modifying the order of modules may cause unexpected results.
You can enable or disable any module at any time however, we recommend to leave some
modules enabled.
We are working on fixing this issue. Sorry for the
inconvenience.
Template Update Policy
The Gray and Color templates are stored on a public
Jorsek GitHub repository.
Jorsek may update the Gray and Color templates on GitHub to fix bugs or
add enhancements. By default, these updates will be reflected in your PDF Generator template.
If you want to use the Gray and Color templates but
you do not want your PDF Generator templates
to be affected by any update made by Jorsek,
contact your Customer Success Manager.
Layout Modules
Determine the document orientation, size, and column count. Add page breaks and blank
pages.
Examine the template code and apply required modifications.
Add topic metadata to the cover page
You can apply this advanced customization by developing
your DITA content in a particular way and by modifying the HTML, CSS, and
XSLT code of the template.
You can apply this advanced customization by developing
your DITA content in a particular way and by modifying the HTML, CSS, and
XSLT code of the template.
Cover
Page HTML
The entire cover page HTML code needs to be commented-out except for a single
empty <div/> element.
“Concept A” is the parent topic of “Concept B” and
“Concept C”
“Concept A” has the @outputclass="landscape"
attribute assigned to the root element
“Concept C” has the @outputclass="portrait"
attribute assigned to the root element
DITA Outputclass Attributes
This module enables you to set the following
@outputclass attributes in the DITA source:
landscape_small
To set the A4 landscape body page size with small margins, assign the
@outputclass="toc_landscape_small" attribute to the
root map element or to the root topic element:
landscape
To set the A4 landscape body page size with regular margins, assign the
@outputclass="toc_landscape" attribute to the root map
element or to the root topic element:
portrait [default]
To set the default A4 portrait body page size with regular margins, assign
the @outputclass="toc_portrait" attribute to the root map
element or to the root topic element:
portrait_large
To set the A4 portrait body page size with large margins, assign the
@outputclass="toc_portrait_large" attribute to the root
map element or to the root topic element:
portrait_small
To set the A4 portrait body page size with small margins, assign the
@outputclass="toc_portrait_small" attribute to the root
map element or to the root topic element:
toc_landscape_large
To set the A4 landscape TOC page size with large margins, assign the
@outputclass="toc_landscape_large" attribute to the
root map element :
toc_landscape_small
To set the A4 landscape TOC page size with small margins, assign the
@outputclass="toc_landscape_small" attribute to the
root map element:
toc_landscape
To set the A4 landscape TOC page size with regular margins, assign the
@outputclass="toc_landscape" attribute to the root map
element:
toc_portrait [default]
To set the default A4 portrait TOC page size with regular margins, assign
the @outputclass="toc_portrait" attribute to the root map
element:
toc_portrait_large
To set the A4 portrait TOC page size with large margins, assign the
@outputclass="toc_portrait_large" attribute to the root
map element:
toc_portrait_small
To set the A4 portrait TOC page size with small margins, assign the
@outputclass="toc_portrait_small" attribute to the root
map element:
Tip: You can assign multiple
@outputclass attributes divided by spaces to a single DITA
element. For example @outputclass="landscape toc_landscape".
For
information on how to assign DITA attributes, see:
Figure 15. Blank Page Before the TOCFigure 16. Blank Page Before a Chapter-Level Topic.
The following example shows a blank page added before “Chapter C” to
make the chapter prints on the right-hand page.
Common Customizations
You can apply customizations by pasting the following code
snippets under the @import rules.
Remove the blank page before the TOC
/* Remove the blank page before the TOC. */
nav {
page-break-before: avoid;
}
Start chapter-level topics on the left-hand side
/* Start each chapter (level-1 topic) on the left page. Insert a blank page before a chapter if needed. */
body > nav ~ article.nested0 {
page-break-before: right;
}
Columns
Lay out elements in columns in the DITA source.
Note: By default, some elements (for example, titles) span across every column. For more information, inspect the template code.
This module enables you to set the following
@outputclass attributes in the DITA source:
two_column
To present content in two columns, assign the
@outputclass="two_column" attribute to a topic
element.
In the following example, the
@outputclass="two_column" attribute is
assigned to the steps element.
three_column
To present content in three columns, assign the
@outputclass="three_column" attribute to a topic
element.
In the following example, the
@outputclass="three_column" attribute is
assigned to the lengthy context element.
four_column
To present content in four columns, assign the
@outputclass="four_column" attribute to a topic
element.
In the following example, the
@outputclass="four_column" attribute is
assigned to “Section A” and “Section B”.
Tip: For PDF Generator, when laying out
content in multiple columns, consider using the landscape page
orientation. For more information, see Orientation Size.
Common Customizations
You can apply customizations by pasting the following code
snippets under the @import rules.
You can apply customizations by pasting the following code
snippets under the @import rules.
Note: By default, there is a limited number of fonts that you can
use for customizations. If you want to add a particular font to the system, contact
your Customer Success Manager.
Set the cover page font
/* Set the cover page font. */
.title-text {
font-family: Verdana, Geneva, Tahoma, sans-serif;
}
Set the table of contents font
/* Set the table of contents font. */
body {
font-family: Verdana, Geneva, Tahoma, sans-serif;
}
Set the header and footer font
/* Set the header and footer font. */
@page {
font-family: Verdana, Geneva, Tahoma, sans-serif;
}
Set the document body font (excluding titles)
/* Set the document body font (excluding titles). */
article,
article * {
font-family: Verdana, Geneva, Tahoma, sans-serif;
}
Set the document body titles font
/* Set the document body titles font. */
.title,
.title *,
.table--title-label,
.fig--title-label,
figcaption:not(figcaption > .desc) {
font-family: Verdana, Geneva, Tahoma, sans-serif;
}
Table of Contents
Style the Table of Contents (TOC).
Note: The default TOC layout is A4 portrait. The TOC layout is not affected by the
@outputclass attributes available in the Orientation Size Module.
You can apply this advanced customization by developing
your DITA content in a particular way and by modifying the HTML, CSS, and
XSLT code of the template.
DITA
The topic that you want to put before the TOC needs to have an
@outputclass attribute assigned to its root tag. You can
use any attribute value but in the following example, the
@outputclass="doc_history" value is used.
In the XSLT tab, add the bold code under the
<xsl:import> tag(s).
Note: The following code snippet assumes that the topic that you want to move before
the TOC has the @outputclass="doc_history" attribute assigned
to its root element.
If you want to move a topic before the TOC with a
different @outputclass attribute value, edit the
underlined code accordingly.
Figure 23. Chapter numbering in the TOCFigure 24. Chapter numbering in the document body
Common Customizations
You can apply customizations by pasting the following code
snippets under the @import rules.
Remove the “Chapter” captions
/* Remove the "Chapter" captions in the TOC. */
nav ul li:not(.topichead):before {
content: counter(toc_level1) ". ";
}
/* Remove the "Chapter" captions in the document body. */
article > .topictitle1:before {
content: counter(section_level1) ". ";
}
The “Context”, “Result”, and “Example” labels are added before empty
elements.
Figure 31. Enabled Style.
The labels preceding empty DITA elements are hidden.
Formatting
Extend DITA content formatting capabilities.
Remember: The extended content formatting works only with the Gray and Color templates. To ensure DITA content
compatibility with other publishing scenarios, avoid overusing the DITA attributes
associated with this style.
The widows property determines the minimum number of lines
allowed to move to a new page. The orphans property
determines the minimum number of lines allowed to stay at the end of a given
page before the paragraph (or other element) breaks to another page.
Figure 32. File path element and variable name element.
The following example shows a file path element that contains a variable name element. The variable name element is automatically wrapped in
<angle brackets>.
Figure 33. System output elementFigure 34. User input element
Common Customizations
You can apply customizations by pasting the following code
snippets under the @import rules.
Do not wrap variable name elements in angle brackets
/* Do not wrap variable name elements in angle brackets. */
.varname::before {
content: "";
}
.varname::after {
content: "";
}
By default, the short description element is rendered as a block element.
Common Customizations
You can apply customizations by pasting the following code
snippets under the @import rules.
Add a border after short description elements or abstract elements
/* Add a border after short description elements or abstract elements. */
.shortdesc:not(.abstract>.shortdesc),
.abstract {
padding-bottom: 10px;
border-bottom: 1px dotted #6f6f6f;
}
You can implement images from an external repository like GitHub or from
your easyDITAcontent library. For more information, see Graphics Implementation.
/* The following examples show custom icons implemented for a regular note and for a tip note.
To modify icons for different note types, use one of the following commented-out selectors instead.*/
/*
.note_trouble > .note__title::before,
.note_fastpath > .note__title::before,
.note_important > .note__title::before,
.note_remember > .note__title::before,
.note_restriction > .note__title::before,
.note_attention > .note__title::before,
.note_caution > .note__title::before,
.note_warning > .note__title::before,
.note_danger > .note__title::before
*/
/* An icon implemented from a public GitHub repository. */.note_note > .note__title::before {
content: "";
margin-right: -20.5px;
background-image:url('https://jorsek.github.io/pdfgen.github.io/shared_images/note-icon.png'); /* provide your own URL */
background-size: 16px 16px;
background-repeat: no-repeat;
width: 16px;
height: 16px;
padding-left: 20.5px;
}
/* An icon implemented from the CCMS content library. */.note_tip > .note__title::before {
content: "";
margin-right: -20.5px;
background-image:url('a15dc8d0-5fb8-11e9-9279-42010a8e0005.png'); /* provide your own UUID */
background-size: 16px 16px;
background-repeat: no-repeat;
width: 16px;
height: 16px;
padding-left: 20.5px;
}
Style note titles
/* The following code selects every note type. If needed, remove selectors that you don't want to use for styling. */
.note_note > .note__title,
.note_trouble > .note__title,
.note_tip > .note__title,
.note_fastpath > .note__title,
.note_important > .note__title,
.note_remember > .note__title,
.note_restriction > .note__title,
.note_attention > .note__title,
.note_caution > .note__title,
.note_warning > .note__title,
.note_danger > .note__title {
text-transform: capitalize;
letter-spacing: 0.1em;
color: #404040;
font-family: Impact, Haettenschweiler, 'Arial Narrow Bold', sans-serif;
font-weight: normal;
}
Change note colors
/* The following code selects every note type. If needed, remove selectors that you don't want to use for styling. */
.note_note > .note__title,
.note_trouble > .note__title,
.note_tip > .note__title,
.note_fastpath > .note__title,
.note_important > .note__title,
.note_remember > .note__title,
.note_restriction > .note__title,
.note_attention > .note__title,
.note_caution > .note__title,
.note_warning > .note__title,
.note_danger > .note__title {
color: #6d597a
}
.note_note,
.note_trouble,
.note_tip,
.note_fastpath,
.note_importan,
.note_remember,
.note_restriction,
.note_attention,
.note_caution,
.note_warning,
.note_danger {
border-left: 5px solid #6d597a;
color: #6d597a;
background-color: #eaac8b;
}
Figure 39. Codeblock elementFigure 40. Code phrase element (inline)Figure 41. Code phrase element (multiple lines).
By default, if a code phrase element cannot fit a page, it takes
several lines and resembles a code block element.
Consider using code block elements for long chunks
of code.
Common Customizations
You can apply customizations by pasting the following code
snippets under the @import rules.
Change the font of code block elements and code phrase elements
/* Change the font of codeblock elements and codeph elements. */
code {
font-family: monospace !important; /* The important property is needed to overwrite the default site settings. */
}
Adjust the colors of code block elements and code phrase elements
/* Adjust the colors of codeblock elements and codeph elements. */
pre.codeblock > code,
pre.codeblock > code *,
code.codeph,
code.codeph * {
background: black;
color: green;
}
.codeblock > code {
border-left: solid 5px green;
}
Figure Image
Adjust the placement of figure elements and image elements.
Remove the left border from definition list entries
/* Remove the left border from definition list entries. */
dt,
dd {
border: none;
padding-left: 0px;
}
Add background shading to definition list entries
/* Add background to the definition list entries. */
dt,
dd {
background-color: #f4f4f4;
padding-top: 5px;
}
dd {
padding-bottom: 5px;
}
Lay out definition list elements in two or more columns
/* Lay out definition list elements in two or more columns. */
dl {
column-count: 2; /* "2" or more */
}
Tip: For PDF Generator, setting a high
number of columns for definition list elements
works well with landscape document orientations. For more information
about the document orientation and page size, see Orientation Size.
Cite Long Quote Quote
Style cite elements, long quote elements, and quote elements.
You can apply customizations by pasting the following code
snippets under the @import rules.
Increase margins before sections
/* Increase margins before sections. */
.section {
margin: 50px 0px 0px 0px !important; /* The important property is needed for sites and is not needed for PDF Gen. */
}
Ordered List Unordered List Step Substep Choice
Adjust the placement of ordered list elements, unordered list elements, step elements, substep elements, and choice elements.
This module enables you to set the following
@outputclass attributes in the DITA source:
process
To change the default “Procedure” label to “Process” before steps
in a task topic, assign the @outputclass="process"
attribute to the root topic element.
Common Customizations
You can apply customizations by pasting the following code
snippets under the @import rules.
You can link to a graphic stored in your easyDITAcontent library by providing the file UUID followed by the file extension.
For more information, see Obtain a Resource UUID.
You can encode graphics to Base64 by using an online tool or by doing it
locally. It is useful if you want to embed graphics in a PDF Generator template.
To convert an image to Base64 by using an online tool, do the following:
Important: The https://www.base64-image.de/ tool is
provided by a third party, and Jorsek, Inc., is not
responsible for any changes in behavior, functionality, or
discontinuation of the tool.
Drag-and-drop an image anywhere in the website.
Click copy image.
To convert an image to Base64 locally on macOS, do the following:
Press Cmd > Space and enter terminal
Press Enter.
Enter base64 -i <image_filepath> -o
<output_filepath>
Where:
<image_filepath> is the path to the
image that you want to encode.
For example:
/Users/<your_username>/Desktop/imageA.png
<output_filepath> is the path to the
file that will contain your Base64-encoded image.
For example:
/Users/<your_username>/Desktop/imageA.txt
Open the <output_filepath> and copy its
contents.
To convert an image to Base64 locally on Windows, do the following:
Click Start and enter:
cmd
Click Command Prompt.
Enter certutil -encode
<image_filepath><output_filepath>
Where:
<image_filepath> is the path to the
image that you want to encode.
For example:
C:\Users\<your_username>\Desktop\imageA.png
<output_filepath> is the path to the
file that will contain your Base64-encoded image.
For example:
C:\Users\<your_username>\Desktop\imageA.txt
Open the <output_filepath> and copy the file
contents between:
-----BEGIN CERTIFICATE-----
and
-----END CERTIFICATE-----
Obtain a Resource UUID
Each resource in easyDITA has its own
Universally Unique Identifier (UUID).
In the content library, right-click a resource and select
Properties.
From the API Info area, copy the UUID.
Styling Annotated Images
In easyDITA, you can add callouts to the images to
annotate them. These callouts can be globally styled according to your branding
needs.
Guidelines
We recommend inserting images inside <fig> elements. Our styling examples are prepared with respect to that suggestion.
Note that you need to use the !important CSS property to
overwrite the styling applied in the SVG Editor embedded in easyDITA.
Remember that the updated styling is applied in the final output and is
visible the Preview mode.
Your PDF Generator publishing
scenario customizations do not overwrite the topic editor
styling.
Annotation callouts are represented by <path>
elements. Modified CSS code will also affect other
<path> elements created in the SVG Editor, specifically those
created either with the Path or
Pencil tool.
Examples
You can apply customizations by pasting the following code
snippets under the @import rules.
Styling the annotations border
You can change the default border look of annotations globally by
applying a proper CSS code. Then, there is no need to individually
change the color of each callout. In the following example, new styling
has been applied to the border color and width.
You may want to apply different type of styling to different kinds of
products instead of imposing the global styling on all images.
Select a figure element with an annotated image.
Go to the Attributes tab in the right
pane.
Apply some meaningful value to the outputclass attribute.
Introduce the same value to the provided code in place of the underlined example-class phrase.
/* Custom annotations styling on specific images */
figure.example-class svg g path {
stroke: #545454 !important;
stroke-width: 2px !important;
fill: #eee !important;
}
The provided code combines a few changes. It modifies the:
border color
border width
fill color
Applying styling to particular annotations only
If there is a specific annotation callout that you want to highlight, you can prepare a global styling for such annotations. This is a much safer option than modifying the individual styling in the editor because it enables you to easily change the appearance of selected annotations globally. Then, you do not need to apply individual styling to the selected annotations in numerous topics.
Annotate your image.
Select the annotation that you want to highlight.
Introduce some meaningful value in the class field.
Save changes by selecting the Close button.
Introduce the same value in the provided code in place of the underlined main-annotation phrase.
/* Custom styling on specific annotations */
figure svg g.main-annotation path {
stroke: #ff0000 !important;
stroke-width: 4px !important;
}
Save your scenario. Styling will be applied only to the annotations with a class specified in the previous steps.
You can change the font of a given annotation too:
/* Custom font on specific annotations */
figure svg g.main-annotation + text {
fill: #ff0000 !important;
font-weight: bold !important;
}
Tip: To ensure
that no one uses a template that is in development to publish a deliverable,
you can hide it from the publishing interface.
Create a PDF Generator Scenario
easyDITAAdministrator can create PDF Generator publishing scenarios.
In the Dashboard interface, from the Administration
menu, select PDF Generator.
Click New scenario.
In the New scenario window, fill in
the Scenario Name field with letters, numbers, hyphens, or
underscore characters only.
The name that you enter will be visible in the publishing interface.
From the Template drop-down menu, select a template.
Tip: The Gray and Color templates are complete and modular templates that you can use to publish your content with very little customizations out of the box.
Click the Browse button
and select where you want to save your configuration files.
Tip: We recommend saving your templates in a
single, obvious, and easily accessible directory in the content library.Figure 67. Suggested Scenarios Directory
If you want to generate chapter-level tables of contents (TOCs):
Select the Chapter Tocs check box.
Specify the maximum chapter-level TOCs depth by filling in the Chapter Toc Depth field.
Enter 5
Figure 68. Main TOC Figure 69. Chapter-Level TOC
If you want to add XSLT parameters:
Click Add XSLT Param.
Fill in the parameter fields.
fig.caption.placement = below
Tip: You can then use the XSLT parameters in the XSLT tab.
Click Create.
Click Save Scenario.
Enable or Disable a PDF Generator Scenario
Administrators can show or
hide a publishing scenario in the publishing interface.
In the Dashboard, click PDF
Generator.
Hover-over a publishing scenario and click .
From the context menu, select an action:
To disable a publishing scenario, select Disable.
Disabled publishing scenarios are not visible in the publishing interface.
To enable a disabled publishing scenario, select
Enable.
Enabled publishing scenarios are visible in the publishing interface.
Delete a PDF Generator Scenario
Administrators can delete
publishing scenarios that are no longer needed.
In the Dashboard, click PDF
Generator.
Hover-over a publishing scenario and click .
From the context menu, select Delete.
If prompted, confirm the scenario deletion.
Locally Develop a PDF Generator Template
You can develop a PDF Generator template on
Windows , macOS, and Linux.
If needed, learn about the CSS features supported by the PDF Generator. See the Prince CSS
Reference.
Ensure that you are an easyDITAAdministrator.
In easyDITA, do the
following:
In the Dashboard interface, from the Administration
menu, select PDF Generator.
Do any of the following:
Under the Name column, click any
scenario.
In the right pane, enable the document preview:
Click Select map to preview.
In the Select Map window, select a map.
Click Select.
Tip: When you change the code, to refresh the preview, click
Generate PDF.
In the right pane, from the HTML tab, copy the HTML
code.
Locally, develop a template by doing the following:
Create a directory for the template development.
Create a directory on your desktop:
C:\Users\user_name\Desktop\PDFGen
(Windows)
/Users/user_name/Desktop/PDFGen
(Mac)
Where user_name is your user name.
Tip: If you need version control, you can keep the template files in a
Git repository or other source control environment.
In the template development directory that you created in 5, create and edit the
testing.html file.
PDFGen/
|- testing.html
Paste the HTML code that you copied in 4 to the testing.html file.
In the template development directory that you created in 5, create a
testing.css file.
PDFGen/
|- testing.html
|- testing.css
Develop the template in the testing.css file.
Locally, preview the template by doing the following:
Open the shell application by doing one of the following:
For Windows, press the Start key and enter cmd
For macOS, press Cmd > Space and enter terminal
For Linux (Ubuntu 19.10), press the Super key and enter terminal
At the prompt, navigate to the template development directory by entering
cd templates_development
Where templates_development is the directory that you
created in 5.
Enter:
C:\Users\user_name\Desktop\PDFGen
(Windows)
/Users/user_name/Desktop/PDFGen
(Mac)
Where user_name is your user name.
Depending on your operating system, perform one of the following actions:
For macOS and Linux, enter prince testing.html -s
testing.css
For Windows, enter "C:\Program Files
(x86)\Prince\engine\bin\prince.exe" testing.html -s
testing.css
Important: The command for Windows
assumes that you used the default settings during the Prince installation. If you
selected a different Prince
installation path, modify the command accordingly.
Tip: For Windows, you can add “C:\Program Files
(x86)\Prince\engine\bin\” as a system path
environment variable. This way, you will be able to run Prince by entering
prince in the command line instead of
entering "C:\Program Files
(x86)\Prince\engine\bin\prince.exe".
Important: This procedure is only applicable for Windows. You do not need to
perform this procedure on macOS or Linux.
Click Start and enter environment
variables
Select Edit the system environment variables.
In the System Properties window, click
Environment Variables.
In the Environment Variables window, under
System variables, double-click
Path.
In the Edit environment variable window, click
New.
Enter "C:\Program Files (x86)\Prince\engine\bin\"
Important: This assumes that you used the default settings during
the Prince installation. If you
selected a different Prince
installation path, enter the relevant path.
In each window, click OK.
You can run Prince by
entering prince in the Command Prompt
now.
The following example shows that you can enter prince
command to run Prince instead of the
longish "C:\Program Files (x86)\Prince\engine\bin\"
command.
.
