bn
/
se


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118
							<!DOCTYPE html
  SYSTEM "about:legacy-compat">
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="UTF-8"><meta name="copyright" content="(C) Copyright 2018"><meta name="DC.rights.owner" content="(C) Copyright 2018"><meta name="DC.Type" content="task"><meta name="description" content="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."><meta name="DC.Relation" scheme="URI" content="../topics/html-customization-plugins.html"><meta name="DC.Relation" scheme="URI" content="../parameters/parameters-base-html.html"><meta name="DC.Relation" scheme="URI" content="../topics/html-customization-css.html"><meta name="DC.Format" content="HTML5"><meta name="DC.Identifier" content="custom-html-plugin-bundle-css"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Bundling CSS in a custom HTML plug-in</title></head><body id="custom-html-plugin-bundle-css"><header role="banner"><div class="header">
  <p>DITA Open Toolkit</p>
  <hr>
</div></header><nav role="toc"><ul><li><a href="../index.html">DITA Open Toolkit 3.0</a></li><li><a href="../release-notes/index.html">Release Notes</a></li><li><a href="../topics/installing-client.html">Installing DITA-OT</a></li><li><a href="../topics/alternative-input-formats.html">Authoring formats</a></li><li><a href="../topics/building-output.html">Building output</a></li><li><a href="../parameters/index.html">Setting parameters</a></li><li><a href="../topics/extending-the-ot.html">Customizing DITA-OT</a><ul><li><a href="../topics/html-customization.html">Customizing HTML</a><ul><li><a href="../topics/html-customization-parameters.html">Setting HTML parameters</a></li><li><a href="../topics/html-customization-properties-file.html">Using a properties file</a></li><li><a href="../topics/html-customization-plugins.html">Custom HTML plug-ins</a><ul><li class="active"><a href="../topics/html-customization-plugin-bundle-css.html">Bundling custom CSS</a></li></ul></li></ul></li><li><a href="../topics/pdf-customization.html">Customizing PDF</a></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/custom-plugins.html">Custom plug-ins</a></li><li><a href="../extension-points/plugin-extension-points.html">Extension points</a></li><li><a href="../topics/migration.html">Migrating customizations</a></li><li><a href="../topics/rebuilding-the-dita-ot-documentation.html">Rebuilding documentation</a></li></ul></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a></li><li><a href="../reference/index.html">Reference</a></li><li><a href="../topics/dita-and-dita-ot-resources.html">Resources</a></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
  <h1 class="title topictitle1" id="ariaid-title1">Bundling CSS in a custom HTML plug-in</h1>
  
  
  <div class="body taskbody"><p class="shortdesc">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.</p>
    <section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
      <p class="p">This scenario walks through the process of creating a very simple plug-in
          (<code class="ph codeph">com.example.html5.custom.css</code>) that creates a new transformation type:
          <span class="keyword option">html5-custom-css</span>. </p>
      <p class="p">The <span class="keyword option">html5-custom-css</span> 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:</p>
      <ul class="ul">
        <li class="li">
          <p class="p">Specify the name of the custom .css file with <span class="keyword parmname">args.css</span>.</p>
          <p class="p">The value of this parameter tells DITA-OT to use the custom .css file provided by the plug-in.</p></li>
        <li class="li">
          <p class="p">Ensure that the custom .css file is copied to the output directory by setting
              <span class="keyword parmname">args.copycss</span> to <span class="keyword option">yes</span>.</p></li>
        <li class="li">
          <p class="p">Set the relative path for .css files in the output folder with <span class="keyword parmname">args.csspath</span>.</p>
          <p class="p">CSS files are copied to the root level of the output folder by default. Setting this parameter places CSS
            files in a dedicated subfolder.</p></li>
      </ul>
      <p class="p">All three parameters are set in the Ant script (<span class="ph filepath">build.xml</span>).</p>
    </section>
    <div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
        <span class="ph cmd">In the <span class="ph filepath">plugins</span> directory, create a directory named
            <span class="ph filepath">com.example.html5.custom.css</span>.</span>
      </li><li class="li step stepexpand">
        <span class="ph cmd">In the new <span class="ph filepath">com.example.html5.custom.css</span> directory, create a plug-in configuration file
            (<span class="ph filepath">plugin.xml</span>) that declares the new <span class="keyword option">html5-custom-css</span> transformation and
          its dependencies.</span>
        <div class="itemgroup stepxmp">
          <figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span>Sample <span class="ph filepath">plugin.xml</span> file</figcaption>
            
            <pre class="pre codeblock"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
<em class="ph i">&lt;!-- This plug-in extends DITA-OT HTML5 processing with a custom CSS file. --&gt;</em>
&lt;plugin id="com.example.html5.custom.css"&gt;
  <strong class="ph b">&lt;require plugin="org.dita.html5"/&gt;</strong>
  <strong class="ph b">&lt;feature extension="dita.conductor.transtype.check" value="html5-custom-css"/&gt;</strong>
  &lt;feature extension="dita.conductor.target.relative" file="build.xml"/&gt;
&lt;/plugin&gt;</code></pre>
          </figure>
          <div class="note note note_note"><span class="note__title">Note:</span> This plug-in will extend the default HTML5 transformation, so the <code class="keyword markupname xmlelement">&lt;require&gt;</code>
            element explicitly defines <span class="ph filepath">org.dita.html5</span> as a dependency.</div>
        </div>
      </li><li class="li step stepexpand">
        <span class="ph cmd">In the <span class="ph filepath">com.example.html5.custom.css</span> directory, create a subdirectory named
            <span class="ph filepath">css</span>.</span>
      </li><li class="li step stepexpand">
        <span class="ph cmd">In the new <span class="ph filepath">css</span> subdirectory, create a file named <span class="ph filepath">custom.css</span> with
          your custom CSS rules.</span>
        <div class="itemgroup stepxmp">
          <figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 2. </span>Sample <span class="ph filepath">custom.css</span> file</figcaption>
            
            <pre class="pre codeblock"><code><em class="ph i">/* These custom styles extend or override DITA Open Toolkit default styles. */</em>

body {
  color: red
}
</code></pre>
          </figure>
          <div class="note tip note_tip"><span class="note__title">Tip:</span> 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.</div>
        </div>
      </li><li class="li step stepexpand">
        <span class="ph cmd">Add an Ant script (<span class="ph filepath">build.xml</span>) to define the transformation type.</span>
        <div class="itemgroup stepxmp">
          <figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 3. </span>Sample <span class="ph filepath">build.xml</span> file</figcaption>
            
            <pre class="pre codeblock"><code>&lt;?xml version='1.0' encoding='UTF-8'?&gt;
<em class="ph i">&lt;!-- This plug-in extends DITA-OT HTML5 processing with a custom CSS file. --&gt;</em>
&lt;project name="com.example.html5.custom.css"&gt;
  &lt;target name="dita2html5-custom-css"&gt;
    &lt;antcall target="dita2html5"&gt;
      <em class="ph i">&lt;!-- Custom .css file used to style output --&gt;</em>
      <strong class="ph b">&lt;param name="args.css" value="${dita.plugin.com.example.html5.custom.css.dir}/css/custom.css"/&gt;</strong>
      <em class="ph i">&lt;!-- Copy the custom .css file to the output directory --&gt;</em>
      &lt;param name="args.copycss" value="yes"/&gt;
      <em class="ph i">&lt;!-- Location of the copied .css file relative to the output --&gt;</em>
      &lt;param name="args.csspath" value="css"/&gt;
    &lt;/antcall&gt;
  &lt;/target&gt;
&lt;/project&gt;</code></pre>
          </figure>
        </div>
      </li></ol>
    <section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>
      <p class="p">The new plug-in directory has the following layout and files:</p>
      <pre class="pre codeblock"><code>com.example.html5.custom.css
├── build.xml
├── css
│   └── custom.css
└── plugin.xml</code></pre>
    </section>
    <section class="section postreq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">What to do next</h2></div>
      <ol class="ol">
        <li class="li">Run <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/bin/<span class="keyword cmdname">dita</span></span>
          <span class="keyword parmname">--install</span> to install the plug-in and make the <span class="keyword option">html5-custom-css</span>
          transformation available.</li>
        <li class="li">Build output with the new transformation type to verify that the plug-in works as intended.
          <pre class="pre codeblock"><code><span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/bin/<span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">my.ditamap</var> <span class="keyword parmname">--format</span>=<span class="keyword option">html5-custom-css</span></code></pre>
        </li>
        <li class="li">Refine the styles in your <span class="ph filepath">custom.css</span> file as necessary.</li>
      </ol>
    </section>
  </div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/html-customization-plugins.html" title="For more complex customizations, you can create custom DITA-OT plug-ins that build on the default XHTML and HTML5 transformations, bundle custom stylesheets, modify the HTML markup, or override other aspects of HTML processing.">Custom HTML plug-ins</a></div></div><div class="linklist relinfo reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/html-customization-css.html" title="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.">Adding custom CSS</a></li></ul></div><div class="linklist relinfo relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters-base-html.html" title="Certain parameters apply to all HTML-based transformation types: HTML5, XHTML, HTML&nbsp;Help, Eclipse help, and TocJS.">HTML-based output parameters</a></li></ul></div></nav></article></main></body></html>