Help us improve — If you have a moment, please answer a few questions to help us understand how you use this site. Take the survey
Bundling CSS in a custom HTML plug-in
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:
The html5-custom-css transformation includes a custom CSS file and sets three 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.
Ensure that the custom .css file is copied to the output directory by setting args.copycss to yes.
Set the relative 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 subfolder.
All three parameters are set in the Ant script (build.xml).
- 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
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.
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.
Add an Ant script (build.xml) to define the transformation type.
The new plug-in directory has the following layout and files:
com.example.html5.custom.css ├── build.xml ├── css │ └── custom.css └── plugin.xml
What to do next
- Run dita-ot-dir/bin/dita --install to install the plug-in and make the html5-custom-css transformation available.
- Build output with the new transformation type to verify that the plug-in works as intended.
dita-ot-dir/bin/dita --input=my.ditamap --format=html5-custom-css
- Refine the styles in your custom.css file as necessary.