Edit online

Transformation Parameters

This list includes the most common customization parameters that are available in the DITA Map PDF - based on HTML5 & CSS transformation scenario. Other standard DITA-OT parameters were omitted for clarity, but they are supported.
Note: These parameters must be prefixed by "-D" when used from a command line.
args.allow.external.coderefs Enables the inclusion of code files that are located outside the DITA map folder hierarchy, referenced using the DITA <coderef> element. Allowed values are yes or no (default).
args.chapter.layout

Specifies whether chapter-level TOCs are generated for bookmaps. When set to MINITOC, a small section with links is added at the beginning of each chapter. The default is BASIC. For details, see: Table of Contents on a Page (Mini TOC).

Allowed values:

  • BASIC - No chapter TOC is created.
  • MINITOC - A chapter-level TOC is generated.
  • MINITOC-BOTTOM-LINKS - A chapter-level TOC is generated, with the links under the chapter description.
args.css You can use this to specify a list of CSS URLs to be used in addition to those specified in the dita.css.list parameter or publishing template. The files must have URL syntax and be separated using semicolons.
args.css.param.* You can use this parameter pattern to set attributes on the root of the merged map. This means you can activate specific CSS rules from your custom CSS using custom attributes. For examples, see: Styling Through Custom Parameters.
args.css.param.clone-referenced-footnotes You can use this parameter to control the footnotes behavior:
  • When set to yes, footnotes that are referenced multiple times throughout a publication are cloned and placed at the bottom of the page for each occurrence.
  • When set to no (default value), only the first footnote reference is placed at the bottom of the page and subsequent references point back to the original footnote.
args.css.param.numbering You can use this parameter to change the numbering of the first-level topics (chapters) and nested topics. Allowed values:
  • shallow - Only the topics from the first level are numbered (chapters). This is the default.
  • deep - All the topics from the map are numbered (nested topics up to level 3).
  • deep-chapter-scope - Similar to deep, but in addition, the page numbers, figures, and table numbers are reset at the start of each first-level topic (chapter). The table and figure titles (and the links to them) are prefixed with the chapter numbers. The generic cross reference links contain both the first-level topic (chapter) numbers and the page numbers to avoid ambiguity. This parameter value is only available for the DITA Map PDF - based on HTML5 & CSS transformation scenario.
  • deep-chapter-scope-no-page-reset - Similar to deep-chapter-scope, but the page numbers do not reset at the start of each first-level topic (chapter). The generic cross reference links contain only the page number. This parameter value is only available for the DITA Map PDF - based on HTML5 & CSS transformation scenario.

For more details, see Numbering Types.
args.css.param.numbering-sections Controls whether or not the sections are included in the table of contents. When set to yes (sections are included), they are numbered according the numbering scheme set by the args.css.param.numbering parameter.
args.css.param.show-onpage-lbl Controls whether or not the links will have an on page NN label after them. This parameter has different defaults, depending on the transformation type. For map transformations (pdf-css-html5 trans type), the default is yes. For topic transformations (pdf-css-html5-single-topic trans type), the default is no.
args.css.param.show-profiling-attributes

Controls whether or not the profiling attributes are displayed in the output.

Allowed values:
  • yes
  • no (default)
args.css.param.title.layout Changes the structure of the title element. In the output, the title area consists of two parts: one is the number of the chapter (and optionally, the sections number), and one is the title text. This parameter allows a switch between normal text flow (in-line flow) and a table layout where the number is placed in one cell and the text in the other (to avoid wrapping text under the chapter number).
  • normal
  • table (avoid wrapping text under counter)
args.draft

Specifies whether or not the content of <draft-comment> and <required-cleanup> elements is included in the output.

Allowed values:
  • no (default) - No draft information is shown in the output.
  • yes - The draft information is shown in the output.
args.figurelink.style
Specifies how cross references to figures are styled in output. Allowed values:
  • NUMBER - Only the number of the figures are shown in links.
  • TITLE - Only the title of the figures are shown in links.
  • NUMTITLE (default) - Both the title and number of the figures are shown in links.
args.gen.task.lbl

Specifies whether or not to generate headings for sections within task topics. Allowed values: YES or NO (default). When set to YES, headings such as "About this task", "Before you begin", "Procedure", or "What to do next", are shown in the task contents.
args.hyph.dir Specifies the directory that contains custom hyphenation dictionaries. Fore more details see: Hyphenation.
args.input Specifies the main DITA map file for your documentation project.
args.keep.output.debug.files Specifies whether or not the debug files generated during the transformation should be kept in the output folder. Allowed values: YES (default) or NO.
args.output.base Specifies the name of the output file without a file extension. By default, the name of the PDF file is derived from the name of the DITA map file. This parameter allows you to override it.
A common use-cases is to use the ditamap title instead of the ditamap filename, the parameter value then become ${xpath_eval(normalize-space(string-join(/*[contains(@class, 'map/map')]/*[contains(@class, 'topic/title')]//text())))}.
Note: To replace spaces by a custom separator the query should call the replace() function: ${xpath_eval(replace(normalize-space(string-join(/*[contains(@class, 'map/map')]/*[contains(@class, 'topic/title')]//text())), '\s', '_'))}.
args.rellinks.group.mode Specifies the related links grouping mode. All links can be grouped into a single "Related Information" group or links grouped by their target type (topic, task, or concept). Allowed values: single-group (default) or group-by-type. Fore more details see: How to Group Related Links by Type.
args.tablelink.style
Specifies how cross references to tables are styled in output. Allowed values:
  • NUMBER - Only the number of the tables are shown in links.
  • TITLE - Only the title of the tables are shown in links.
  • NUMTITLE (default) - Both the title and number of the tables are shown in links.
clean.temp Specifies whether or not the DITA-OT deletes the files in the temporary directory after it finishes a build. Allowed values: yes (default) or no.
chemistry.security.policy Specifies a Java policy file that applies to the Chemistry process. A template can be found here: plugins/com.oxygenxml.pdf.css/lib/oxygen-pdf-chemistry/config/chemistry.policy.
chemistry.security.workspace Specifies a directory where the temporary files and font cache created by the Chemistry process need to be stored. This becomes required when the chemistry.security.policy is specified.
chemistry.security.resources.dir Path to an additional folder that Chemistry will use to read its resources (CSS, images). The process already has read access to the input map folder, the publishing templates folder, and the OPE install folder. This optional parameter should only be used when the chemistry.security.policy parameter is set.
chemistry.security.resources.host The host, specified as name:port, that Chemistry will use to get resources (e.g. CSS files, images, fonts). This optional parameter should only be used when the chemistry.security.policy parameter is set.
css.processor.path.antenna-house Path to the Antenna House executable file that needs to be run to generate the PDF (for example, C:\path\to\AHFCmd.exe on Windows).
css.processor.path.chemistry Path to the Oxygen PDF Chemistry executable file that needs to be run to generate the PDF (for example, C:\path\to\chemistry.bat on Windows). If this parameter is not set, the plugin will use the system's PATH environment variable to locate and start Oxygen PDF Chemistry.
css.processor.path.prince Path to the Prince executable file that needs to be run to generate the PDF (for example, C:\path\to\prince.exe on Windows).
css.processor.type Specifies the processor to use for the transformation. Allowed values: chemistry (default), antenna-house, or prince.
default.language Specifies the default language for source documents. Examples: fr, de, zh, etc. Depending on the transformation type, the actual number of supported languages can vary, see: Localization.
drop.block.margins.at.page.boundary Specifies that the top and bottom margins associated with a block element should be discarded when the block is at the top or bottom of the page. Allowed values: YES (default) or NO.
editlink.ditamap.edit.url Use this parameter to add an Edit link next to the topic title in the WebHelp output. When a user clicks the link, the topic is opened in Oxygen XML Web Author or Content Fusion where they can make changes that can be saved to a file server. The value should be set as the edit URL of the main DITA map used for publishing your output. The easiest way to obtain the URL is to open the map in Web Author or Content Fusion and copy the URL from the browser's address bar.
editlink.additional.query.parameters You can use this optional parameter to add additional parameters to be appended to each generated edit link. Each parameter must start with & (for example: &tags-mode=no-tags).
editlink.remote.ditamap.url (deprecated) Use this parameter in conjunction with editlink.web.author.url to add an Edit link next to the topic title in the PDF output. When a user clicks the link, the topic is opened in Oxygen XML Web Author where they can make changes that can be saved to a file server. The value should be set as the custom URL of the main DITA map. For example, a GitHub custom URL might look like this: https://getFileContent/oxygenxml/userguide/master/UserGuide.ditamap.
editlink.web.author.url (deprecated) This parameter needs to be used in conjunction with editlink.remote.ditamap.url to add an Edit link next to the topic title in the PDF output. When a user clicks the link, the topic is opened in Oxygen XML Web Author where they can make changes that can be saved to a file server. The value should be set as the URL of the Web Author installation. For example: https://www.oxygenxml.com/oxygen-xml-web-author/.
enable.chunk.processing Enables the processing of the @chunk attribute. By default, this stage is skipped but it needs to be enabled, for example, if both the @chunk and @copy-to attributes are present on a <topicref>. Accepted values: true or false.
enable.latin.glyph.substitutions When set to yes (default), glyph substitution is enabled (if the particular font supports it). This applies to Latin-based scripts only (the substitutions are always enabled in other types of scripts). If you encounter problems rendering or copying accented glyphs (e.g. umlauts or other diacritics), it might be helpful to set this parameter to no to disable the font glyph substitutions. Another example of a case when you might need to disable the substitutions is a situation where an accented character cannot be mapped to a compound glyph, resulting in the glyph not being rendered in the PDF output.
Warnings:
  • Disabling substitutions also disables Latin ligatures.
  • Disabling substitutions is not recommended unless absolutely necessary. It is better practice to use another font if you can find one that does not have the rendering issues.
expand.xpath.in.svg.templates Expands XPath expressions (whose format is ${expression}) contained in SVG templates. Allowed values: yes (default) or no.
figure.title.placement Controls the title placement of the figures, relative to the image. Possible values include top (default) and bottom.
filter.unused.glossentries When set to no (default), all glossary entries are displayed in the glossary. If set to yes, only referenced entries are displayed.
fix.external.refs.com.oxygenxml

The DITA Open Toolkit usually has problems processing references that point to locations outside of the processed DITA map directory. This parameter is used to specify whether or not the application should try to fix such references in a temporary files folder before the DITA Open Toolkit is invoked on the fixed references. The fix has no impact on your edited DITA content. Allowed values: true or false (default).
hide.frontpage.toc.index.glossary When set to yes, the generated structures (table of contents, index list, front page, etc.) are removed from the output. The default is no.
image.resolution You can use this parameter to set the default resolution used by images. It works mainly on vector images since raster images have their resolution defined in their metadata. The default is 96 (dpi). For more information, see how to change images resolution.
pdf.accessibility When set to yes, the PDF output is generated in compliance with the PDF/Universal Accessibility standard (also known as ISO 14289). The default is no.
pdf.archiving.mode

Specifies the archiving mode. The PDF output will be generated in compliance with the PDF/A standard.

Allowed values (not set by default):
  • PDF/A-1a
  • PDF/A-1b
  • PDF/A-2a
  • PDF/A-2b
  • PDF/A-2u
  • PDF/A-3a
  • PDF/A-3b
  • PDF/A-3u
pdf.version Use this parameter to specify the version of the produced PDF. It has no impact on the set of PDF features used by the engine, but may be used to signal a compatibility level to the PDF readers. The default is 1.5.
pdf.security.restrict.printhq Restricts high quality printing. Used for protecting the PDF Document. The restriction is off by default. Accepted values: yes or no.
pdf.security.restrict.assembledoc Restricts assembling document (e.g. adding pages). Used for protecting the PDF Document. The restriction is off by default. Accepted values: yes or no.
pdf.security.restrict.accesscontent Restricts extracting text and graphics. Used for protecting the PDF Document. The restriction is off by default. Accepted values: yes or no.
pdf.security.restrict.fillinforms Restricts filling in existing interactive forms. Used for protecting the PDF Document. The restriction is off by default. Accepted values: yes or no.
pdf.security.restrict.annotations Restricts filling in existing interactive forms. Used for protecting the PDF Document. The restriction is off by default. Accepted values: yes or no.
pdf.security.restrict.print Restricts printing. Used for protecting the PDF Document. The restriction is off by default. Accepted values: yes or no.
pdf.security.restrict.copy Restricts copying content. Used for protecting the PDF Document. The restriction is off by default. Accepted values: yes or no.
pdf.security.restrict.edit Restricts copying content. Used for protecting the PDF Document. The restriction is off by default. Accepted values: yes or no.
pdf.security.user.password User password. The document can be opened using this password. When the owner password parameter is not specified, the user password gives full rights to the people using it. When the owner password parameter is specified, the people can open the document using the user password but restrictions will apply. Missing by default.
pdf.security.owner.password Owner password. There are no restrictions for people using this password.
pdf.security.encrypt.metadata Encrypts the metadata. By default active when other security parameters are set. Accepted values: yes or no.
show.changes.and.comments

When set to yes, the user comments, colored highlights and tracked changes are shown in the output.
show.changes.and.comments.as.changebars

When set to yes (default) and the show.changes.and.comments parameter is also set to yes, the user comments and tracked changes are shown as change bars in the PDF output. This parameter can be used in conjunction with the show.changes.and.comments.as.pdf.sticky.notes parameter to choose whether the change bars are displayed in footnotes or sticky notes. You can override this from your customization CSS.
show.changes.and.comments.as.pdf.sticky.notes When set to yes (default) and the show.changes.and.comments parameter is also set to yes, the user comments and tracked changes are shown in the PDF output as sticky note annotations. When set to no, the comments and tracked changes are left in the document model and are styled by the default CSS rules as footnotes. You can override this from your customization CSS.
show.changed.text.in.pdf.sticky.notes.content When set to yes (default) and both the show.changes.and.comments and show.changes.and.comments.as.pdf.sticky.notes parameters are also set to yes, the inserted and deleted text is shown in the sticky note annotations. When set to no, only the inserted and deleted labels are shown in the annotations (this is useful for search scope).
show.image.map.area.numbers When set to yes, a counter for each area from the image map is displayed over the image, near the defined shape. The default is no.
show.image.map.area.shapes When set to yes, each of the image map area shapes is displayed with a translucent fill over the image. You can use this to debug your image maps. The default is no.
show.media.as.link When set to yes, media objects will not appear and an external link is generated for each one instead.
sort.and.group.glossentries When set to no (default), elements in the glossary are sorted based upon the document order. If set to yes, elements in the glossary are sorted alphabetically and grouped by their first letter.
store-type Setting this parameter to memory will increase the processing speed and thus, could help decrease the publishing time.
table.title.placement Controls the placement of the title for tables. Possible values include top (default) and bottom.
table.title.repeat Specifies whether or not a table caption should repeat on other pages when the table spans onto multiple pages. The caption is not repeated for tables nested in lists or other tables. Allowed values are yes (default) or no.
use.css.for.embedded.svg When set to yes (default), the CSS files specified in the publishing template or by the args.css parameter are also applied on embedded SVG elements. Allowed values are yes and no.
use.navtitles.in.all.links Specifies whether a <navtitle> defined in a topic or a topic reference should be used as the display name for all links or only in the table of contents. Allowed values are yes and no (default).
parallel Specifies whether or not certain pre-processing tasks should be run in parallel. Setting this parameter to true may add a small increase to the publishing speed. Allowed values are: true and false (default).
The following parameters can be used to specify a publishing template:
pdf.publishing.template Specifies the path to the folder containing the custom PDF template.
pdf.publishing.template.descriptor Specifies the name of the descriptor file to be loaded from the PDF template folder or package. If not specified, the first encountered descriptor file is loaded.
The following parameter is available on all DITA transformations when using the Oxygen Publishing Engine:
args.disable.security.checks Specifies whether or not to load external entities that are not solved through catalogs. For security reasons, the default is no.

Allowed values:

  • yes
  • no (default)
The following parameters are only available for the DITA PDF - based on HTML5 & CSS single DITA topic transformation scenario (pdf-css-html5-single-topic trans type):
args.root.map Specifies the path of the root map file used to expand the key references in the published topic.
args.enable.root.map.key.processing

Indicates whether or not the keys should be processed using the root map parameter.

Allowed values:

  • auto (default)
  • yes
  • no