Packaging your customization as a w2x plugin

Command-line utility w2x and desktop application w2x-app support plugins.

Let’s suppose you have created a plugin called “rss” which may be used to convert DOCX to RSS. Once registered with w2x, this plugin may be invoked as it were a stock conversion, for example:

w2x -o rss my.docx my.xml

Other example, using a plugin called “wh5_zip” (see description below):

w2x -o wh5_zip -p zip.include-top-dir false my.docx

In w2x-app, you'll find the registered plugins in the "Convert to" combobox and in the "Output format" screen of the setup assistant.

Anatomy of a plugin

A plugin is simply a plain text file, using an UTF-8 character encoding, having a ".w2x_plugin" file suffix, containing a number of w2x command-line arguments and starting with comment lines containing information about the plugin (for example, its name). Example, w2x_install_dir/sample_plugins/rss/rss.w2x_plugin:

### rss

### plugin.outputDescription: RSS 2.0

### plugin.outputExtension: xml

### plugin.multiFileOutput: no


-e w2x:xed/main.xed

-t rss.xslt

# Image files not useful here.


-p cleanUp.files "%{~pO}/%{~nO}_files"

Field Name

Default Value


Basename of the ".w2x_plugin" file without its extension.

The name of the plugin (a single word).


The name of the plugin.

A short description (just a few words) of the output format of this plugin.



Preferred extension for the files created by this plugin.



Whether this plugin creates multiple files or just a single one. A boolean: “true”, “yes”, “on”, “1” or “false”, “no”, “off”, “0”.

The above rss plugin converts DOCX to RSS. This process is partly implemented by XSLT 1.0 stylesheet w2x_install_dir/sample_plugins/rss/rss.xslt which is part of this plugin. Stylesheet rss.xslt transforms its input, the semantic XHTML 1.0 Transitional file created by the Edit step (invoked using -e w2x:xed/main.xed), to RSS.

Aside XSLT 1.0 stylesheets, a plugin may also include XED scripts as well as ".jar" files containing support code and/or custom conversion steps implemented in Java™. Example, w2x_install_dir/sample_plugins/wh5_zip/wh5_zip.w2x_plugin:

### plugin.outputDescription: Web Help ZIP containing "semantic" (X)HTML 5.0

### plugin.outputExtension: zip

-o webhelp5

-p webhelp.split-before-level 8

-p webhelp.use-id-as-filename yes

-p webhelp.omit-toc-root yes

-p webhelp.wh-layout simple

# Generate all HTML files in a subdirectory of the output directory

# having the same basename as the ".zip" output file.

-p convert.xhtml-file "%{~pO}/%{~nO}/%{~nO}.xhtml"

-p transform.out-file "%{~pO}/%{~nO}/%{~nO}_tmp.xhtml"

-p webhelp.out-file "%{~pO}/%{~nO}/%{~nO}.html"

-p cleanUp.files "%{~pO}/%{~nO}/%{~nO}_tmp.xhtml"


-p zip.out-file "%{O}"

The above wh5_zip plugin specializes the stock conversion called webhelp5 (Web Help containing XHTML 5.0) by giving specific values to some of its parameters (e.g. -p webhelp.wh-layout simple) and also by archiving all the output files in a single “.zip” file.

This last step, -step:ZipStep:zip, is implemented by a custom conversion step found in w2x_install_dir/sample_plugins/wh5_zip/src/ This Java™ code is compiled and archived in w2x_install_dir/sample_plugins/wh5_zip/zip_step.jar by the means of ant build file w2x_install_dir/sample_plugins/wh5_zip/src/build.xml.

Note that these ".jar" files, just like the ".w2x_plugin" files, are automatically discovered and loaded by w2x and w2x-app during their startup phase.

Registering a plugin with w2x

A plugin is registered with both w2x and w2x-app by copying all its files anywhere inside directory w2x_install_dir/plugin/.

However it's strongly recommended to group all the files comprising a plugin in a subdirectory of its own having the same name as the plug-in (e.g. w2x_install_dir/plugin/rss/).

If the .dmg distribution has been used to install XMLmind Word To XML on the Mac, the plugin directory is

Alternatively, this plugin may be installed anywhere you want provided that the directory containing the ".w2x_plugin" file is referenced in the W2X_PLUGIN_PATH environment variable. Example: set W2X_PLUGIN_PATH=C:\Users\John\w2x\rss;C:\temp\w2x_plugins.

The W2X_PLUGIN_PATH environment variable (or, equivalently, the W2X_PLUGIN_PATH Java™ system property; e.g. -DW2X_PLUGIN_PATH=C:\Users\John\w2x\rss;C:\temp\w2x_plugins) may contain absolute or relative directory paths separated by semi-colons (";"). A relative path is relative to the current working directory.

The W2X_PLUGIN_PATH environment variable may also contain "+", which is a shorthand for w2x_install_dir/plugin/. Windows example: set W2X_PLUGIN_PATH=..\sample_plugins;+. Linux/macOS example: export W2X_PLUGIN_PATH=+;/home/john/w2x_plugins.