Yendra Waney, Oceaneering
December 1, 2020

When I started at Oceaneering, Microsoft Word was the basis of the documentation. So, I started the migration to DITA on the very first day. My manager at that time didn’t know about DITA, but he was pleased that I rewrote a manual with 20% fewer words. By the way, that was not because of DITA. Now the next challenge was to make the DITA output a bit similar to the Microsoft Word formatting. In other words, I needed to customize the output.

Almost every organization that uses DITA wants to customize the DITA output. You can see examples of such customized output on the web. Examples are:

If you look at these output examples, the customization looks difficult. Can you make customization simple? Can you get the output that you want? If you search on the internet about this subject, there is enough information. However, that information is conceptual.  What you really need is instructions on how to make your documentation output the way you want.

So, how do you customize your DITA output yourself?

DITA converters: The black box comes in colors

Look at DITA as a process. Start with the XML code that you feed to the DITA converter/transform. That converter does the magic. It turns the XML into a document that you can publish.


For me, the DITA converter is a black box. You know only what goes in and what goes out, for example, XML in, PDF out. But different vendors make different black boxes. They work differently. One is more opaque than the other. Let me mention three of these DITA converters/transforms.

What counts is what comes out

All three DITA generators make a standard output. For most companies, that’s not good enough. They want at least their company logo on the front page. That means that you need to modify the output somehow.  Few people care about how you do that.

So, where do you customize the DITA process to get the output you want? Let’s look at the DITA process again. You have three stages, three opportunities. Authoring, conversion, post-conversion output.

In the authoring stage, you can modify the XML code to force a page break and a forced line feed. But that’s about it. The output stage has more possibilities for customization. For example, you could Acrobat Pro or Nitro Pro to shape your PDFs. But these two solutions have issues – go ahead and add or change the HTML code and make your HTML page the way you want; finish your publication with desktop publishing, but if something bothers you, a typo or a wrong picture, and you have to update your content, you must do the customization all over again.

So, maybe the best place to customize your output is during the conversion/transformation stage. Let’s go back to the three DITA converters/transforms. The OpenToolkit is too difficult for me. Framemaker is too expensive. So, I gave XMLMind ditac a try.

KISS DITA

Personally, I chose XMLMind ditac for these reasons.

  • You can do the customization through parameters.
  • The default output is close to the target.
  • The tool is free of charge and open source.

Let’s keep things simple.

Using XMLMind, the parameters that you change are in the files of the ditac folders (ditac-3_8_0⁩ -> ⁨xsl⁩ -> fo⁩).  As an example, let’s look at the transform to PDF.

The customization runs like this recipe.

  1. Know what to customize.
  2. Search for the parameter in ditac XSLT parms table of the XMLMind ditac manual.
  3. Find the file with that parameter.
  4. Change the value of that parameter.
  5. Generate the output.
  6. Write down what you did.

Maybe it’s easy to explain with examples.

Example 1: Bigger font

First, look in the parms table to find the parameter associated with the font size.

Parameter Value Description
base-font-size Default value:
‘10pt’		 The size of the “main font” of the document. All the other font sizes are computed relatively to this font size.
  1. Open a command line.
  2. Navigate to the ditac\fo folder.
  3. Search for the file containing “base-font-size”
  4. Open that file.
  5. Change the parameter <xsl:param name=”base-font-size” select=”’10pt'”/> to <xsl:param name=”base-font-size” select=”’12pt'”/>.
  6. Convince yourself that the font is bigger.
  7. Write everything for future use — No problem for a techwriter.

Example 2: Change the font to sans-serif

The XSLT parameters table mentions body-font-family. This parm is in fo->foParams.xsl.

  1. Open foParams.xsl.
  2. Locate <xsl:param name=”body-font-family” select=”‘serif’”/>
  3. Change ‘serif’ to ‘sans-serif’.

Example 3: Change the header and the footer

  1. Open fo->foParams.xsl.
  2. Change the following from:
             <xsl:param name="header-left" select="‘’”/>
             <xsl:param name="header-center" select="'{{document-title}}’”/>
             <xsl:param name="header-right" select="‘’”/> 
          To
             <xsl:param name="header-left" select=“‘{{document-date}}’”/>
             <xsl:param name="header-center" select="'{{document-title}}’”/>
             <xsl:param name="header-right" select="'{{image(My_company_logo.svg)}}'"/>

Example 4: Enable and change the note icons

  1. Open common->commonParams.xsl.
  2. Change the parameter <xsl:param name=”use-note-icon” select=”‘no’”/> to <xsl:param name=”use-note-icon” select=“’yes'”/>
  3. Copy the icon set of your choice (PNG) into the folder fo->resources.

Example 5: Make the font size of the title bigger

In this example, the XSLT parameters table does not document the parameter that you want to change. In this case, it’s guessing.

  1. Search for font-size in folder fo. You get several hits, but most likely you find the right parameter in ditac_titlePage.xsl.
  2. Open ditac_titlePage.xsl.
  3. Locate <xsl:attribute name=”font-size”>2em</xsl:attribute>
  4. Change ’2em’ to ‘3em’.

In the last step, you make the title page 3 times bigger than the ‘base-font-size’.

In short

The DITA publishing process happens in three stages: authoring, conversion, output. In each of these stages, you can do your manipulation to customize the output. However, the conversion stage is the most practical and has enough opportunities. If you take the XMLMind DITA converter, ditac,  you can customize your output through parameters. The challenge now is to see what parameters you might change, where you can find these, and to what value to change them. Often, the XMLMind documentation helps. Sometimes you need to guess.

If you want to exchange thoughts about DITA output customization, let’s connect on LinkedIn.