Plug-in descriptor file

The plug-in descriptor file (plugin.xml) controls all aspects of a plug-in, making each extension visible to the rest of the toolkit. The file uses pre-defined extension points to locate changes, and then integrates those changes into the core DITA-OT code.

Validating plug-ins

DITA-OT includes a RELAX NG schema file that can be used to validate the plugin.xml files that define the capabilities of each plug-in.

To ensure the syntax of your custom plug-in is correct, include an xml-model processing instruction at the beginning of the plugin.xml file, immediately after the XML prolog:

xml-model href="https://www.dita-ot.org/rng/plugin.rnc" type="application/relax-ng-compact-syntax"

If your authoring environment does not apply this schema automatically, point your editor to *dita-ot-dir*/resources/plugin.rnc to associate the schema with your plug-in file.

Plug-in identifiers

Every DITA-OT plug-in must have a unique identifier composed of one or more dot-delimited tokens, for example, com.example.rss. This identifier is used to identify the plug-in to the toolkit for installation, processing, and when determining plug-in dependencies.

Note: The default DITA-OT plug-ins use a reverse domain naming convention, as in org.dita.html5; this is strongly recommended to avoid plug-in naming conflicts.

Each token can include only the following characters:

Lower-case letters (a-z)
Upper-case letters (A-Z)
Numerals (0-9)
Underscores (_)
Hyphens (-)

<plugin>

The root element of the plugin.xml file is <plugin>, which has a required @id attribute set to the unique plug-in identifier.

Plug-in elements

The <plugin> element can contain the following child elements:

<extension-point>
An optional element that defines a new extension point that can be used by other DITA-OT plug-ins.
The following attributes are supported:
Attribute
Description
Required?
id
Extension point identifier
Yes
name
Extension point description
No
Like plug-in identifiers, extension point identifiers are composed of one or more dot-delimited tokens.
Note: Extension point identifiers should begin with the identifier of the defining plug-in and append one or more tokens, for example, org.dita.example.pre.
<extension-point id="dita.xsl.html5" name="HTML5 XSLT import"/>

Attribute	Description	Required?
id	Extension point identifier	Yes
name	Extension point description	No

<feature>

An optional element that supplies values to a DITA-OT extension point.

The following attributes are supported:

Attribute	Description	Required?
extension	Identifier of the DITA-OT extension point	Yes
value	Comma separated string value of the extension	Either the `@value` or `@file` attribute must be specified
file	Name and path of a file containing data for the extension point. Depending on the extension point, this might be specified as an absolute path, a path relative to the `plugin.xml` file, or a path relative to the DITA-OT root.

If more than one `<feature>` element supplies values to the same extension point, the values are additive. For example, the following are equivalent:

```language-xml
<feature extension="org.dita.example.extension-point" value="a,b,c"/>
```

```language-xml
<feature extension="org.dita.example.extension-point" value="a"/>
<feature extension="org.dita.example.extension-point" value="b"/>
<feature extension="org.dita.example.extension-point" value="c"/>
```

<metadata>
An optional element that defines metadata.
The following attributes are supported:
Attribute
Description
Required?
type
Metadata name
Yes
value
Metadata value
Yes
<metadata type="foo" value="bar"/>
<require>
An optional element that defines plug-in dependencies.
The following attributes are supported:
Attribute
Description
Required?
plugin
The identifier of the required plug-in. To specify alternative requirements, separate plug-in identifiers with a vertical bar.

Attribute	Description	Required?
type	Metadata name	Yes
value	Metadata value	Yes

Attribute	Description	Required?
plugin	The identifier of the required plug-in. To specify alternative requirements, separate plug-in identifiers with a vertical bar.

|Yes| |importance|Identifies whether the plug-in is required (default) or optional. DITA-OT provides a warning if a required plug-in is not available.|No|

```
<require plugin="org.dita.html5"/>
```

<template>
An optional element that defines files that should be treated as templates.
Template files can be used to integrate DITA-OT extensions. Templates typically extend the default transformation-type-specific build files via <dita:extension> elements. When the plug-in installation process runs, template files are used to recreate build files, and the specified extension points are replaced with references to the appropriate plug-ins.
The following attributes are supported:
Attribute
Description
Required?
file
Name and path to the template file, relative to the plugin.xml file
Yes
<template file="build_dita2html5_template.xml"/>

Attribute	Description	Required?
file	Name and path to the template file, relative to the `plugin.xml` file	Yes

<transtype>

An optional element that defines a new output format (transformation type).

The following attributes are supported:

Attribute	Description	Required?
name	Transformation name	Yes
desc	Transformation type description	No
abstract	When true, sets the transformation type as “abstract”, meaning it can be extended by other plug-ins, but cannot be used directly. For example, the `org.dita.base` plug-in defines an abstract “base” transformation type that is extended by other DITA-OT plug-ins.

|No| |extends|Specifies the name of the transformation type being extended|No|

```language-xml
<transtype name="base" abstract="true" desc="Common">
  [...]
  <param name="link-crawl"
         desc="Specifies whether to crawl only topic links found in maps, or all discovered topic links."
         type="enum">
    <val>map</val>
    <val default="true">topic</val>
  </param>
  [...]
</transtype>

```

The `<transtype>` element may define additional parameters for the transformation type using the following child elements.

-   **`<param>`**

    An optional element that specifies a parameter for the transformation type.

    The following parameter attributes are supported:

    |Attribute|Description|Required?|
    |---------|-----------|---------|
    |**name**|Parameter name|Yes|
    |**desc**|Parameter description|No|
    |**type**|Parameter type \(enum, file, string\)|Yes|
    |**deprecated**|When true, identifies this parameter as deprecated|No|
    |**required**|When true, identifies this parameter as required|No|

-   **`<val>`**

    A child of `<param>` \(when `@type`=enum\) that specifies an enumeration value.

    The following attributes are supported:

    |Attribute|Description|Required?|
    |---------|-----------|---------|
    |**default**|When true, sets the enumeration value as the default value of the parent `<param>`|Only for the default `<val>`|

Any extension that is not recognized by DITA-OT is ignored. Since DITA-OT version 1.5.3, you can combine multiple extension definitions within a single plugin.xml file; in older versions, only the last extension definition was used.

Example plugin.xml file

The following is a sample of a plugin.xml file. This file adds support for a new set of specialized DTDs, and includes an override for the XHTML output processor.

This plugin.xml file would go into a directory such as DITA-OT/plugins/music/ and referenced supporting files would also exist in that directory. A more extensive sample using these values is available in the actual music plug-in, available on SourceForge.

<plugin id="org.metadita.specialization.music">
  <feature extension="dita.specialization.catalog.relative"
           file="catalog-dita.xml"/>
  <feature extension="dita.xsl.xhtml" file="xsl/music2xhtml.xsl"/>
</plugin>

Related information

Creating a new plug-in extension point

Adding a new transformation type

Last modified: 13 February 2024