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 still supported.

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 will be generated.
  • MINITOC-BOTTOM-LINKS - A chapter-level TOC will be 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.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 will be numbered (chapters). This is the default.
  • deep - All the topics from the map will be 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.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.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 will be shown in links.
  • TITLE - Only the title of the figures will be shown in links.
  • NUMTITLE (default) - Both the title and number of the figures will be 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 master 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.
args.tablelink.style
Specifies how cross references to tables are styled in output. Allowed values:
  • NUMBER - Only the number of the tables will be shown in links.
  • TITLE - Only the title of the tables will be shown in links.
  • NUMTITLE (default) - Both the title and number of the tables will be 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
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/oxyengxml/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/.
figure.title.placement Controls the title placement of the figures, relative to the image. Possible values include top (default) and bottom.
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.
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.
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 will be 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 will be displayed with a translucent fill over the image. You can use this to debug your image maps. The default is no.
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).
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 it is not specified, the first encountered descriptor file will be 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