diff --git a/dev_ref/html-customization-plugin-bundle-css.dita b/dev_ref/html-customization-plugin-bundle-css.dita new file mode 100644 index 000000000..3c46b3181 --- /dev/null +++ b/dev_ref/html-customization-plugin-bundle-css.dita @@ -0,0 +1,116 @@ + + + + + + Bundling CSS in a custom HTML plug-in + + Bundling custom CSS + + You can create a DITA-OT plug-in that provides a custom stylesheet with the font settings 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. + + +

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 transformation includes a custom CSS file and sets three parameters to + integrate the custom stylesheet in the generated HTML5 output:

+
    +
  • Specify the custom .css file with args.css
    • +
  • Copy the custom .css file to the output directory with args.copycss
    • +
  • Set the path for .css files in the output folder with args.csspath
    • +
+ + + + 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 transformation and + its dependencies. + + + Sample <filepath>plugin.xml</filepath> 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" type="txt"/> + <feature extension="dita.conductor.target.relative" value="build.xml" type="file"/> +</plugin> + + 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. + + + Sample <filepath>custom.css</filepath> file + /* These custom styles extend or override DITA Open Toolkit default styles. */ + +body { + color: red +} + + + 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. + + + Sample <filepath>build.xml</filepath> 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"> + <antcall target="dita2html5"> + <!-- Custom .css file used to style output --> + <param name="args.css" value="${dita.plugin.com.example.html5.custom.css.dir}/css/custom.css"/> + <!-- Copy the custom .css file to the output directory --> + <param name="args.copycss" value="yes"/> + <!-- Location of the copied .css file relative to the output --> + <param name="args.csspath" value="css"/> + </antcall> + </target> +</project> + + + + + +

The new plug-in directory has the following layout and files:

+ com.example.html5.custom.css +├── build.xml +├── css +│ └── custom.css +└── plugin.xml + + +
    +
  1. Run + --install to install the plug-in and make the + transformation available.
    2. +
  2. Build output with the new transformation type to verify that the plug-in works as intended. + --input=my.ditamap --format= +
    3. +
  3. Refine the styles in your custom.css file as necessary.
    4. +
+ + + diff --git a/dev_ref/html-customization.ditamap b/dev_ref/html-customization.ditamap index e02885f1e..99c703373 100644 --- a/dev_ref/html-customization.ditamap +++ b/dev_ref/html-customization.ditamap @@ -7,6 +7,8 @@ - + + +