Adding custom CSS

To modify the appearance of the default HTML output generated by the DITA Open Toolkit, you can reference a custom Cascading Style Sheet (CSS) file with the typography and colors that define your corporate identity.

About this task

You can use this approach when you need to adjust the look and feel of the default output for a single project, but don’t want to create a custom DITA-OT plug-in.

You can version the CSS file along with the DITA source files in your project, so stylesheet changes can be tracked along with modifications to topic content.

You may also find this approach useful as you develop a custom stylesheet. Once the CSS rules stabilize, you can bundle the CSS file in a custom DITA-OT plug-in to ensure consistent HTML output across projects.


  1. Create a custom CSS file and store it in your project along with your DITA source files.
    Note: As a starting point, you can use the CSS file that is used for the DITA-OT documentation. This file is available in the installation folder under docsrc/resources/dita-ot-doc.css.
  2. Set the args.css parameter to the name of your custom CSS file.

    The value of this parameter should be only the file name. The relative path to the file can be specified with args.cssroot.

  3. Set the args.copycss parameter to yes.

    This setting ensures that your custom CSS file will be copied to the output directory.

  4. Set args.cssroot to the folder path that contains your custom CSS file.

    The value you enter here will be interpreted relative to the location of the input map file. If your map is stored at the root level of your project folder and the CSS file is stored in a subfolder named resources, set args.cssroot to resources.

  5. Optional: Set args.csspath to specify the location of the CSS file in the output folder.

    If args.csspath is not set, the custom CSS file will be copied to the root level of the output folder. To copy the CSS file to a subfolder named css, set args.csspath to css.


Tip: For an example of HTML output generated using this method, see the HTML5 version of the DITA-OT documentation included in the installation folder under doc/index.html.