XML plugin user's guide

Version 2.8.5 (May 31 2013)

Slava Pestov

Dale Anson

Eric Le Lay

Robert McKinnon

Martin Raspe

Jakub Roztocil

Alan Ezust

Legal Notice

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no "Invariant Sections", "Front-Cover Texts" or "Back-Cover Texts", each as defined in the license. A copy of the license can be found in the file COPYING.DOC.txt included with jEdit.

The XML plugin itself is released under the GNU General Public License. A copy of the GPL can be found in the jEdit online help.

This version of the XML plugin for jEdit combines the HtmlSideKick plugin and EcmaScript parser by Dale Anson, the JavaScriptSideKick by Martin Raspe, the CSS SideKick by Jakub Roztocil, and the XmlIndenter plugin by Robert McKinnon, providing five distinct Sidekick parsers and four different completion services, as well as an indenting service for the Beauty plugin, ISO-RELAX and jing-trang, for validation and translation of documents that use Relax-NG schemas.

Table of Contents


This documentation assumes at least basic knowlege of HTML and XML.

The XML plugin makes jEdit one of the most advanced free Website editing tools available. It combines parsers for XML, HTML, JSP, Sidekick, and CSS files. Here are its features:

  • On-the-fly validation of XML files with DTD, XSD, or RNG schemas.

  • Tag, attribute, and entity completion popups for XML, HTML and CSS

  • Display of the element tree in a dockable window, for XML, HTML, JavaScript, JSP, and CSS

  • Matching tag highlighting

  • One click insertion of tags and entities

  • Graphical form to edit tags and attributes

  • With a keystroke, jump to matching tag or bracket

  • And more.

XML and SideKick

To provide most of its functionality, the XML plugin relies on the SideKick plugin. What this means is that Sidekick must be enabled, and docked (preferably to your right or left) and parsing your current buffer in order for certain operations to succeed. Select Plugins - SideKick - SideKick, and click on the little arrow, which is the docking menu in the upper left corner, to set its docked position.

Note: Since the XML plugin provides a separate Sidekick parser for HTML versus XML, and it may be possible to parse some documents with both, you may get different results depending on how 'strict' the HTML/XML syntax is used in the document.

XML and other plugins

The XML plugin can take advantage of other plugins, in addition to the required ones like Sidekick.

  • If you want to follow hyperlinks in HTML or XML, you'll have to install the Hyperlinks plugin.

  • The XML plugin comes with templates for a few common HTML and XML document types (e.g. HTML 4.01 strict, XSD, and XSL. To use them, install the Templates plugin and restart jEdit.

The XML insert window

Plugins>XML>XML Insert displays the XML insert window. This window is floating by default, but it can be docked into the view from the dock menu (a little arrow in the upper right corner), or from the Docking pane of the Global Options dialog box.

This window lists elements that may be inserted at the caret position, all declared entities, and all IDs (element attributes with a value type of ID).

Clicking an element in the list with the left mouse button will insert it into the buffer and show the Edit Tag dialog box for specifying attributes. See the section called “The edit tag dialog box” for information about the Edit Tag dialog box. Clicking an element with the right mouse button will insert it in the text area, but the Edit Tag dialog box will not be shown.

Clicking an entity will insert it into the buffer.

Clicking an ID with the left mouse button will insert it into the buffer; clicking with the right mouse button will move the caret to the element that declares it.

If text is selected, each selection is wrapped in a pair of opening and closing tags. This is a very powerful feature; you can select any number of text chunks, and surround them with tags, all sharing a common set of attributes.

The edit tag dialog box

The Edit Tag dialog box can be opened in any of these ways:

  • Invoking Plugins>XML>Edit Tag at Caret.

  • Double-clicking a tag in the text area while holding down Control.

  • Hitting return in the completion dialog, if the option is set from the XML Options.

  • Clicking on an element from the XML Insert dockable.

The dialog box lists all declared attributes for the current tag in a table. The columns of the table are as follows:

  • Set. A check box that controls if the attribute is specified or not. Required attributes are always specified.

  • Name. The name of the attribute.

  • Type. This will either be "text" or "choice". If the attribute is required, "required" will be appended.

  • Value. For "text" attributes, this is a text field. For "choice" attributes, this is a combo box. Depending on the schema, some attributes might define a default value.

    Note that special characters entered in the text field are automatically converted to entities if necessary.

The Preview text field shows what the tag will look like with all currently-specified attributes. Clicking OK will insert the tag into the buffer.

Miscellaneous features

If the caret is positioned on a tag, the corresponding opening or closing tag will be highlighted in the text area. You can disable this feature, or change the tag highlight color in the XML>Xml pane of the Plugins>Plugin Options dialog box.

Plugins>XML>Go to Matching Tag moves the caret to the corresponding opening or closing tag.

Plugins>XML>Close Last Open Tag inserts a closing tag for the last opened tag.

Plugins>XML>Remove All Tags removes all tags from the current buffer, leaving only text.

Plugins>XML>Split Tag splits the current tag at the cursor, and creates a new tag at the same level. This is useful when editing HTML, DocBook or similar documents, for inserting many <p> or <para> tags. This command tries to match the current indenting style.

Plugins>XML>Characters to Entities converts special characters to entities in the current selection.

Plugins>XML>Entities to Characters converts entities to characters in the current selection.

Plugins>XML>Generate DTD generates a DTD from the XML instance document in the current buffer. Generation of XSD and RelaxNG schemata is planned for the future.

Plugins>XML>Copy XPath inserts in the clipboard an XPath to current element. For instance, if the caret is inside the style element of an HTML page, Copy XPath will copy /html/head[1]/style[1] in the clipboard. This might be useful when writing an XSL template over a complex document. Copy XPath should handle namespaces and prefixes gracefully :

  • namespaces and local-names are used for comparison - not prefixes, though prefixes found in the document are retained;

  • only the first of 2 prefixes bound to the same namespace in the source document will be used in the XPath;

  • if the same prefix is bound to different namespaces, the second instance of the prefix will get a numbered suffix to distinguish it in the XPath.


DTDs or Document Type Definitions, are a common way to specify schemas. While an older standard, are still widely used. Buffers which have an associated DTD are validated for errors, and completion popups are shown for elements, attributes, and entities. DTDs are specified by including markup like the following near the start of an XML file:

<?xml version="1.0"?>
 <!DOCTYPE PUBLIC "public ID" "system ID">

Or alternatively:

<?xml version="1.0"?>
 <!DOCTYPE SYSTEM "system ID">

XSDs, or XML schemas, perform a similar function to DTDs, however they are a newer standard and support some features that DTDs do not, like namespaces. Buffers which have an associated schema are validated for errors, and completion popups are shown for elements and entities.

Schemas are specified with a http://www.w3.org/2001/XMLSchema-instance namespace in the document's root element:


Or if the target schema has an associated namespace:

<dictionary           xmlns="http://www.xml-cml.org/schema/stmml"
          xsi:schemaLocation="http://www.xml-cml.org/schema/stmml ../schema/stmml.xsd
          http://www.xml-cml.org/schema/cml2/core ../schema/cmlCore.xsd">

In all cases, the XML parser will first look for the specified system or public ID in the plugin's built-in catalog, along with any catalog files specified in the XML>Catalogs pane of the Plugins>Plugin Options dialog box.

Catalog files must either be in OASIS OPEN or XML catalog format. These two formats are documented below.

If the DTD or XSD cannot be located in the catalogs, the plugin will ask if it should be downloaded and cached for future use in the dtds subdirectory of the jEdit settings directory.

The download cache can be cleared using the Plugins>XML>Clear DTD Cache command.

Built-in DTDs

The XML plugin catalogs the following DTDs which are included with jEdit itself, or the XML plugin.

  • DTDs declared by jEdit: actions.dtd, catalog.dtd, dockables.dtd, perspective.dtd, plugins.dtd, recent.dtd, registers.dtd, services.dt, xmode.dtd.

  • A few plugin DTDs: commando.dtd (Console plugin), sqlServerType.dtd (SQL plugin).

  • XHTML 1.0 and XHTML 1.1 DTDs, referenced using one of the following public IDs:

    • -//W3C//DTD XHTML 1.0 Frameset//EN

    • -//W3C//DTD XHTML 1.0 Strict//EN

    • -//W3C//DTD XHTML 1.0 Transitional//EN

    • -//W3C//DTD XHTML 1.1//EN

  • DocBook 4.4 DTDs, referenced with the -//OASIS//DTD DocBook XML V4.4//EN public ID.

For example, these doctypes are recognized by the XML plugin, and when they are used, tell the XML plugin to load a built-in DTD, and provide you with completion popups for elements and attributes.

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"   "docbookx.dtd">
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "xhtml11-flat.dtd">
Tag and entity completion

If the less-than symbol ("<") is typed and no other key is pressed within a specified delay (half a second by default), a tag list popup will be shown. Note that only tags which the parent element is allowed to contain are listed. The arrow keys can be used to select a tag; if you start typing a tag name, only tags whose names begin with the already-entered text will be shown.

Pressing Space or > will insert the currently selected tag into the buffer. Pressing Enter will insert the tag and show the Edit Tag dialog box; see the section called “The edit tag dialog box”.

Attribute Completion works in a similar manner - when the XML plugin detects that you are inside a tag and about to enter an attribute name, it will provide you with a list of possible attributes or completions of attributes if it can obtain this information from the schema.

Entity completion works in a similar manner; typing & will show an entity list popup. Pressing Space, Enter or ; will insert the currently selected entity into the buffer.

Typing "</" will automatically close the last open tag.

Another convenient feature inserts a closing tag when you finish typing an opening tag. It is disabled by default, but can be activated from the plugin options.

These features can be enabled, disabled and configured in the SideKick and XML>XML pane of the Plugins>Plugin Options dialog box.

Built-in completion information

The XML plugin supports element and entity completion for the following file types using completion information built in to the plugin:

  • HTML files

  • XSL stylesheets (xsl)

  • XSD XML schema definitions

  • build.xml - Ant build files


XML files are validated against their DTD, XSD or RNG schema. If no schema can be loaded, only minimal error checking will be performed. No validation of any kind is performed for HTML files, but XHTML files can be validated using their regular schema.

Any errors found while parsing XML are handled by the ErrorList plugin; in other words, they are highlighted in the text area, and shown in the Plugins>Error List>Error List window. See the documentation for the ErrorList plugin for details.

DTDs (document type definitions), XSDs (w3c XML Schemas), and Relax-NGs are three different standards for defining XML Schemas, to describe which elements and entities are allowed within a specific context. In order to implement completion or validation, the XML plugin needs to be able to load a schema. A few file types for which no schema is available are supported using built-in completion information included with the plugin.

Customizing validation

Validation can be disabled on a global basis in the XML>XML pane of the Plugins>Plugin Options dialog box. It can also be disabled on a per-buffer basis by inserting the following in the first of last 10 lines of the buffer:


Namespaces processing can be disabled on a per-buffer basis by inserting the following in the first or last 10 lines of the buffer:


Why would you do that ? If you use the XHTML plus Math 1.1 DTD, you will get an error because the DTD uses a prefixed name IS10744:arch somewhere, which is incompatible with namespaces. The typical error message is :

A colon is not allowed in the name XXX when namespaces are enabled.

DTD Validation can be disabled on a per-buffer basis by inserting the following in the first of last 10 lines of the buffer:


This way, one can use DTDs for entities and a schema for validation. Here is a sample of what you'd do :

<!-- :xml.validate.ignore-dtd=true: -->
<!DOCTYPE article [
  <!ENTITY % isolat1 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN//XML" 
                "http://www.oasis-open.org/docbook/xmlcharent/0.3/iso-lat1.ent" >
  <!ENTITY % isogrk1 PUBLIC "ISO 8879:1986//ENTITIES Greek Letters//EN//XML"
                "http://www.oasis-open.org/docbook/xmlcharent/0.3/iso-grk1.ent" >
<title>Using entities like &ecute; </title>

Finding Schemas

Validation will be performed if it is enabled (see the section called “Customizing validation”) and if a schema or a DTD can be found.

While DTDs and XSD schemas are declared in the document (see the section called “Schemas”), Relax NG schemas are not declared in the document. Therefore, there must be an external mean of specifying the RNG schema.

You can do this:

  • on a per-buffer basis by inserting the following in the first or last 10 lines of the buffer:

    :xml.validation.schema=URI to the schema:

    You can use an absolute or relative URI or even an URI that will be resolved as a system Id by some catalog (e.g. locate.rng).

  • on a per directory and/or global basis, by using schema mapping rules (the so called schemas.xml). This is consistent with the nXML mode for Emacs (it's even 100% compatible !). These powerful mapping rules work on filenames, paths, root element, namespace, etc.

When the XML plugin parses an XML buffer, it will look for a file named schemas.xml in the same directory. Or, if it doesn't exist, for a global file in the settings directory (under JEDIT_SETTINGS/plugins/xml.XmlPlugin/schemas.xml), and finally for the built-in file (XML.jar!/xml/dtds/schemas.xml). The rules contained in this file are given the public Id, system Id, doctype, prefix, local name, namespace of the parsed document. The first rule to match returns the schema that will be used for validation.

You can edit manually these schemas.xml files. There is a built-in rule to find their schema, so XML completion and validation should work. The schema is under xml/dtds/locate.rng in the XML.jar archive (simply open your mapping document and use Plugins>XML> Open Schema).

There are also three actions associated with schema mapping :

You can set the type of current buffer to a known type via Plugins>XML> Set Schema Type.... You will be prompted for a type, like :


for Relax NG Schemas


for schemas.xml


for any well formed XML

You can also directly point to an XSD or RNG schema via Plugins>XML> Set Schema.... You will be able to choose a schema file from the VFS browser.


It does not work from a remote filesystem yet !

Both of these actions will create a schemas.xml file alongside the current buffer. If such a file exists already, it is updated.


The current implementation will retain any existing rule, but will erase any comment and any formatting in the document, so beware that all commented-out section of the schema-mapping will disappear next time you use Set Schema....

Disabling the schema-mapping

If, for some reason, you want to disable this schema-mapping mechanism, you can do it on a global basis by unchecking the enable schema mapping checkbox, in the XML>Xml pane of the Plugins>Plugin Options.

You can also disable schema-mapping on a per-buffer basis (let's say on a file in a read-only directory), by inserting the following in the first or last 10 lines of the buffer:


The XML parser will no more try to find a schema using schemas.xml. However, it will still pick a schema defined via a buffer-local property in a buffer, or if you set a schema via Set Schema... or Set Schema Type....

What will happen if you use Set Schema... and schema-mapping is disabled is that the chosen schema won't be saved and any existing schemas.xml in the same directory won't be updated. You will have to select the schema again next time you edit the buffer.

Conversely, Set Schema Type... will still work. It will even propose you schema types defined in a schemas.xml in the same directory as the buffer. However, the schema-type won't be saved and the schemas.xml won't be updated. Also, if you update the definition of the typeId (ie. you change its target to another schema), the schema defined for the buffer won't be updated and you'll have to do Set Schema Type... again.

Seeing the schema which validated a buffer

Finally, Plugins>XML> Open Schema will let you see the schema associated to current buffer, regardless of wether it is specified as a buffer-local property, via the menu item, or via a schema-mapping rule.

Translating between schemas

Thanks to Trang's schema translation capabilities, you will be able to translate from any of DTD, RNG, RNC, XML instances to DTD, RNG, RNC, XSD.

Trang (http://www.thaiopensource.com/relaxng/trang.html, James Clark and others) is Copyright © 2002, 2003, 2008 Thai Open Source Software Center Ltd.

A copy of its user-guide is included here.

You may do a basic conversion of current buffer using the xml-translate-to-dtd, xml-translate-to-rnc, xml-translate-to-rng, xml-translate-to-xsd actions.

You may specify advanced options using Plugins>XML> Translate Schema using Trang. The meaning of each parameter is described in Trang's user manual (docs/trang-manual.html).

The output of Trang is converted to jEdit buffers, so that you may review them before saving. Any existing file will be overwritten but you'll get its contents back, using undo.

XML Inclusion

It is sometimes necessary to split a long XML document into smaller parts, or to assemble parts in different ways. This can be achieved via external entities (a DTD feature) or via XInclude.

Child Documents

When editing an XML file which is included from another file, it can be desirable for validation to always start at the root file, rather than the one that is currently being edited. For example, you might be writing a user manual using DocBook, with each chapter split into its own XML file. This can be achieved by inserting the following in the first or last 10 lines of each child file:

:xml.root=relative or absolute path of root document

Note that even if this property is specified, the Structure Browser window only shows elements defined in the current buffer. However, when validating an included file, validation errors will be reported for all files included from the root file.

External entities

External entities were used in the user guide for jEdit 4.4 and earlier (see excerpt of users-guide.xml). The DOCTYPE declaration lists some entities, which are referenced via &your_entity;. This is similar to #include directives in C or C++.

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!ENTITY conventions SYSTEM "conventions.xml">


<title>your title</title>


The inclusion is performed before DTD validation which allows the ID/IDREF validation to succeed : ie. a section declared with id="ID1" in one file can be referenced from another included file via <xref linkend="ID1"/>. For validation in jEdit, you will also need the section called “ Child Documents ”.


XInclude defines a namespace associated with the URI http://www.w3.org/2001/XInclude. The XInclude namespace contains two elements with the local names include and fallback.

 --XML Inclusions (XInclude) Version 1.0 (Second Edition) W3C Recommendation 15 November 2006

The jEdit 4.5 FAQ and users guide both use XIncludes to join together child documents into a whole.

The following example shows an inclusion similar to excerpt of users-guide.xml.

<title>your title</title>
<xi:include  href="conventions.xml"
             xmlns:xi="http://www.w3.org/2001/XInclude" />

XInclude can be activated on a global basis in the XML>XML pane of the Plugins>Plugin Options dialog box. It can also be activated on a per-buffer basis by inserting the following in the first of last 10 lines of the buffer:


You can fine-tune the way relative URIs will be interpreted in the included fragment : either resolve the URIs based on the URI of the fragment, or based on the URI of the parent (see http://www.w3.org/TR/xinclude/#base). This is controlled globally in the option pane or via the property xml.xinclude.fixup-base-uris on a per-buffer basis.

See the following example:


Note that DTD validation would fail on ID/IDREF attributes (ids and linkends). This is because the document seen by the DTD validator is prior to XInclude resolution. You are then forced to use either XML Schemas or RelaxNG validation. For validation in jEdit, you will also need the section called “ Child Documents ”.

For more informations regarding XInclude and docbook, you should reed Chapter 22 of DocBook XSL: The Complete Guide by Bob Stayton : http://docs.huihoo.com/docbook/docbook-xsl-complete-guide-3rd/ModularDoc.html

Xinclude is activated in xsltproc via the --xinclude command-line switch.

OASIS OPEN catalog format

Each line in an OASIS OPEN catalog file must look like one of the following:

  • -- comment - comments are ignored.

  • SYSTEM "system ID" "new system ID" - maps the first system ID to the second.

  • PUBLIC "public ID" "new system ID" - maps the public ID to the system ID.

OASIS XML catalog format

Catalog files in the OASIS XML catalog format are themselves XML files, and must have the following DOCTYPE declaration:

<![CDATA[<!DOCTYPE catalog
  PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"

The XML plugin bundles the above DTD so you can use the completion features to construct an OASIS XML catalog.

Hyperlinks support

If the Hyperlinks plugin is installed and active, some attributes will be available for navigation. To show them, simply hold the Ctrl key and hover over them with the mouse. A solid blue underline will appear under attribute values recognised as hyperlinks. Then, clicking on the link will open the referenced document in a buffer and in some cases move to the referenced element.

Hereafter is the list of supported hyperlinks in the XML mode. xml:base attributes are used to resolve relative hyperlinks.

  • href attributes in XInclude (<xi:include href="..."/>). Fragments are not supported: the buffer is opened and that's all.

  • simple XLinks (<myelt xlink:href="..."/>). Only simple links are supported and the fragment identifier is ignored: the buffer is opened and that's all.

  • IDREF attributes, when the buffer has been parsed and the attribute has the IDREF datatype. This includes DocBook 4.x links (<xref linkend="id"/>). IDREFS attributes are also supported. Each idref is highlighted on its own. Datatype is derived from the RNG, XSD, or DTD grammar used for the document.

  • XML Schema (XSD) schema location (<myelt xsi:schemaLocation="ns1 url1...">) and no-namespace schema location (<myelt xsi:noNamespaceSchemaLocation="url">). Multiple namespace-url couples are supported.

  • attributes with datatype anyURI, e.g. XSD include and import (<xs:include schemaLocation="url"/>). Datatype is derived from the RNG, XSD, or DTD grammar used for the document.

  • DocBook ulink (<ulink url="...">). This is really the url attribute of an ulink element in no namespace.

Hereafter is the list of supported hyperlinks in the HTML mode. Supported hyperlinks are all attributes with type URI in the HTML 4.01 spec. Links to other documents and anchors inside document are supported, but fragment identifiers in other documents are not. The HTML/HEAD/BASE element is used to resolve URIs, if present.

  • href attributes in a, area, link elements.

  • longdesc, usemap attributes of img element.

  • cite attribute of q, blockquote, ins and del elements.

  • usemap attribute of input and object elements.

  • src attribute of script element.

  • Attributes with type anyURI are recognised as hyperlinks.

  • Attributes with type IDREF and IDREFS work as hyperlinks to the referenced element.

XML Indenter

The Xml Indenter plugin allows you to indent the XML contents of the current open buffer. You can invoke the "Indent XML" action via a keyboard shortcut or toolbar icon; this can be configured from "Utilities->Global Options->jEdit->Shortcuts" or "Utilities->Global Options->jEdit->Tool Bar" respectively.

The indent width amount and whether to use soft (emulated with spaces) tabs can be configured in the buffer options: "Utilities->Buffer Options".

The following improvements should eventually be made to the Indent XML feature:

  • Correctly support different line separator encodings.

Configuring whitespace preservation options

You can configure elements whose enclosing text nodes should have whitespace preserved by going to: "Plugins->Plugin Options->XML Indenter".

On the options pane click the add button and in the dialog enter the qualified name of an element whose whitespace should be preserved.

A qualified name consists of the element name plus any namespace prefix if there is one. For example the XML Indenter comes preconfigured with whitespace preservation for elements named xsl:text, text and tspan.

You can remove elements from the list by selecting them and clicking the remove button.

A. Change log

Click here to see the detailed changelog of the XML plugin. There are also separate changelogs for XmlIndenter and JavaScript SideKick, two plugins that were merged into the XML plugin.

B. Feedback

All jEdit users are encouraged to join the mailing list to give feedback or ask questions of other users and developers.

The preferred way to send bug reports against the XML plugin is to use the jEdit Plugin Bugs Tracker.

Feature requests can be found on the jEdit Plugin feature requests tracker.

Development questions should be posted to the jEdit development mailing-list .