You can create a DITA-OT plug-in that provides a custom stylesheet with the typography and colors that
define your corporate identity. Coworkers can install this plug-in to ensure consistent HTML output across projects
without having to copy the stylesheet to each project.
About this task
This scenario walks through the process of creating a very simple plug-in
(com.example.html5.custom.css) that creates a new transformation type:
html5-custom-css.
The html5-custom-css transformation includes a custom CSS file and sets four parameters to
integrate the custom stylesheet in the generated HTML5 output. These parameter settings make the following
changes:
Specify the name of the custom CSS file with args.css.
The value of this parameter tells DITA-OT to use the custom.css file provided by the
plug-in.
Specify the css subfolder of the plug-in as the source directory for custom CSS with
args.cssroot.
Ensure that the CSS file is copied to the output directory by setting args.copycss to
yes.
Set the destination path for CSS files in the output folder with args.csspath.
CSS files are copied to the root level of the output folder by default. Setting this parameter places CSS
files in a dedicated css subfolder.
All four parameters are set in the Ant script (build.xml).
Procedure
In the plugins directory, create a directory named
com.example.html5.custom.css.
In the new com.example.html5.custom.css directory, create a plug-in configuration file
(plugin.xml) that declares the new html5-custom-css transformation and
its dependencies.
Figure 1. Sample plugin.xml file
<?xml version="1.0" encoding="UTF-8"?>
<!-- This plug-in extends DITA-OT HTML5 processing with a custom CSS file. -->
<plugin id="com.example.html5.custom.css">
<require plugin="org.dita.html5"/><feature extension="dita.conductor.transtype.check"
value="html5-custom-css"/>
<feature extension="ant.import" file="build.xml"/>
</plugin>
Note: This plug-in will extend the default HTML5 transformation, so the <require>
element explicitly defines org.dita.html5 as a dependency.
In the com.example.html5.custom.css directory, create a subdirectory named
css.
In the new css subdirectory, create a file named custom.css with
your custom CSS rules.
Figure 2. Sample custom.css file
/* These custom styles extend the DITA Open Toolkit default styles */
body {
color: red
}
Tip: When you first create the plug-in, you may want to include a rule in your custom stylesheet
that makes it readily apparent when the custom styles are applied (the example above will change body text
to “red”). Once you have verified that the plug-in works as intended, replace the placeholder rule with your
own custom styles.
In the com.example.html5.custom.css root directory, add an Ant script
(build.xml) to define the transformation type.
Figure 3. Sample build.xml file
<?xml version='1.0' encoding='UTF-8'?>
<!-- This plug-in extends DITA-OT HTML5 processing with a custom CSS file. -->
<project name="com.example.html5.custom.css">
<target name="dita2html5-custom-css.init">
<!-- Custom .css file used to style output --><property name="args.css" value="custom.css"/><!-- Source directory that contains the custom .css file --><property name="args.cssroot"
value="${dita.plugin.com.example.html5.custom.css.dir}/css"/><!-- Copy the custom .css file to the output directory --><property name="args.copycss" value="yes"/><!-- Location of the copied .css file relative to the output --><property name="args.csspath" value="css"/>
</target>
<target name="dita2html5-custom-css"
depends="dita2html5-custom-css.init,
dita2html5"/>
</project>
Results
The new plug-in directory has the following layout and files: