-
Notifications
You must be signed in to change notification settings - Fork 96
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Draft topic on bundling custom CSS in plug-in #118
Signed-off-by: Roger Sheen <roger@infotexture.net>
- Loading branch information
1 parent
733905d
commit 18a5050
Showing
2 changed files
with
119 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,116 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> | ||
| <!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. --> | ||
|
|
||
| <task id="custom-html-plugin-bundle-css"> | ||
| <title>Bundling CSS in a custom HTML plug-in</title> | ||
| <titlealts> | ||
| <navtitle>Bundling custom CSS</navtitle> | ||
| </titlealts> | ||
| <shortdesc>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.</shortdesc> | ||
| <taskbody> | ||
| <context> | ||
| <p>This scenario walks through the process of creating a very simple plug-in | ||
| (<codeph>com.example.html5.custom.css</codeph>) that creates a new transformation type: | ||
| <option>html5-custom-css</option>. </p> | ||
| <p>The <option>html5-custom-css</option> transformation includes a custom CSS file and sets three parameters to | ||
| integrate the custom stylesheet in the generated HTML5 output:</p> | ||
| <ul> | ||
| <li>Specify the custom .css file with <parmname>args.css</parmname></li> | ||
| <li>Copy the custom .css file to the output directory with <parmname>args.copycss</parmname></li> | ||
| <li>Set the path for .css files in the output folder with <parmname>args.csspath</parmname></li> | ||
| </ul> | ||
| </context> | ||
| <steps> | ||
| <step> | ||
| <cmd>In the <filepath>plugins</filepath> directory, create a directory named | ||
| <filepath>com.example.html5.custom.css</filepath>.</cmd> | ||
| </step> | ||
| <step> | ||
| <cmd>In the new <filepath>com.example.html5.custom.css</filepath> directory, create a plug-in configuration file | ||
| (<filepath>plugin.xml</filepath>) that declares the new <option>html5-custom-css</option> transformation and | ||
| its dependencies.</cmd> | ||
| <stepxmp> | ||
| <fig> | ||
| <title>Sample <filepath>plugin.xml</filepath> file</title> | ||
| <codeblock><?xml version="1.0" encoding="UTF-8"?> | ||
| <i><!-- This plug-in extends DITA-OT HTML5 processing with a custom CSS file. --></i> | ||
| <plugin id="com.example.html5.custom.css"> | ||
| <b><require plugin="org.dita.html5"/></b> | ||
| <b><feature extension="dita.conductor.transtype.check" value="html5-custom-css" type="txt"/></b> | ||
| <feature extension="dita.conductor.target.relative" value="build.xml" type="file"/> | ||
| </plugin></codeblock> | ||
| </fig> | ||
| <note>This plug-in will extend the default HTML5 transformation, so the <xmlelement>require</xmlelement> | ||
| element explicitly defines <filepath>org.dita.html5</filepath> as a dependency.</note> | ||
| </stepxmp> | ||
| </step> | ||
| <step> | ||
| <cmd>In the <filepath>com.example.html5.custom.css</filepath> directory, create a subdirectory named | ||
| <filepath>css</filepath>.</cmd> | ||
| </step> | ||
| <step> | ||
| <cmd>In the new <filepath>css</filepath> subdirectory, create a file named <filepath>custom.css</filepath> with | ||
| your custom CSS rules.</cmd> | ||
| <stepxmp> | ||
| <fig> | ||
| <title>Sample <filepath>custom.css</filepath> file</title> | ||
| <codeblock><i>/* These custom styles extend or override DITA Open Toolkit default styles. */</i> | ||
|
|
||
| body { | ||
| color: red | ||
| } | ||
| </codeblock> | ||
| </fig> | ||
| <note type="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.</note> | ||
| </stepxmp> | ||
| </step> | ||
| <step> | ||
| <cmd>Add an Ant script (<filepath>build.xml</filepath>) to define the transformation type.</cmd> | ||
| <stepxmp> | ||
| <fig> | ||
| <title>Sample <filepath>build.xml</filepath> file</title> | ||
| <codeblock><?xml version='1.0' encoding='UTF-8'?> | ||
| <i><!-- This plug-in extends DITA-OT HTML5 processing with a custom CSS file. --></i> | ||
| <project name="com.example.html5.custom.css"> | ||
| <target name="dita2html5-custom-css"> | ||
| <antcall target="dita2html5"> | ||
| <i><!-- Custom .css file used to style output --></i> | ||
| <b><param name="args.css" value="${dita.plugin.com.example.html5.custom.css.dir}/css/custom.css"/></b> | ||
| <i><!-- Copy the custom .css file to the output directory --></i> | ||
| <param name="args.copycss" value="yes"/> | ||
| <i><!-- Location of the copied .css file relative to the output --></i> | ||
| <param name="args.csspath" value="css"/> | ||
| </antcall> | ||
| </target> | ||
| </project></codeblock> | ||
| </fig> | ||
| </stepxmp> | ||
| </step> | ||
| </steps> | ||
| <result> | ||
| <p>The new plug-in directory has the following layout and files:</p> | ||
| <codeblock>com.example.html5.custom.css | ||
| ├── build.xml | ||
| ├── css | ||
| │ └── custom.css | ||
| └── plugin.xml</codeblock> | ||
| </result> | ||
| <postreq> | ||
| <ol> | ||
| <li>Run <filepath conref="../resources/conref-task.dita#ID/dita-cmd"/> | ||
| <parmname>--install</parmname> to install the plug-in and make the <option>html5-custom-css</option> | ||
| transformation available.</li> | ||
| <li>Build output with the new transformation type to verify that the plug-in works as intended. | ||
| <codeblock><filepath conref="../resources/conref-task.dita#ID/dita-cmd"/> <parmname>--input</parmname>=<varname>my.ditamap</varname> <parmname>--format</parmname>=<option>html5-custom-css</option></codeblock> | ||
| </li> | ||
| <li>Refine the styles in your <filepath>custom.css</filepath> file as necessary.</li> | ||
| </ol> | ||
| </postreq> | ||
| </taskbody> | ||
| </task> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters