diff --git a/xdoc/src/plugin-resources/site.jsl b/xdoc/src/plugin-resources/site.jsl
index 61a49c80..e7f96104 100644
--- a/xdoc/src/plugin-resources/site.jsl
+++ b/xdoc/src/plugin-resources/site.jsl
@@ -976,10 +976,11 @@
   <jsl:template match="text()"><x:expr select="."/></jsl:template>
 
   <!-- copy any other elements through -->
-  <!-- This does not work with entities, see http://jira.codehaus.org/browse/MPXDOC-17 -->
-  <!--<jsl:template match="*" trim="false"><jsl:copy trim="false"><jsl:applyTemplates trim="false"/></jsl:copy></jsl:template>-->
-  <jsl:template match="*" trim="false"><jsl:copyOf select="."/></jsl:template>
-   
+  <jsl:template match="*" trim="false"><jsl:copy trim="false"><jsl:applyTemplates trim="false"/></jsl:copy></jsl:template>
+
+  <jsl:template match="entity" trim="false"><jsl:copyOf select="."/></jsl:template>
+
+
   <!-- process a message -->
   <!-- Key is more important than message... -->
   <jsl:template match="message" trim="true">
diff --git a/xdoc/src/plugin-test/test01/xdocs-replacement/test.xml b/xdoc/src/plugin-test/test01/xdocs-replacement/test.xml
index f0b81aea..f3fbe029 100644
--- a/xdoc/src/plugin-test/test01/xdocs-replacement/test.xml
+++ b/xdoc/src/plugin-test/test01/xdocs-replacement/test.xml
@@ -40,44 +40,44 @@
         <tr>
           <td>_module</td>
           <td><code>&lt;module&gt;</code></td>
-          <td>&_module;</td>
+          <td><entity>&_module;</entity></td>
         </tr>
         <tr>
           <td>module</td>
-          <td><a href="descriptor.html#module">module</a></td>
-          <td>&module;</td>
+          <td><a href="descriptor.html#module"><code>&lt;module&gt;</code></a></td>
+          <td><entity>&module;</entity></td>
         </tr>
         <tr>
           <td>apache.a</td>
           <td>Apache</td>
-          <td>&apache.a;</td>
+          <td><entity>&apache.a;</entity></td>
         </tr>
         <tr>
           <td>apache.b</td>
           <td>&lt;Apache&gt;</td>
-          <td>&apache.b;</td>
+          <td><entity>&apache.b;</entity></td>
         </tr>
         <tr>
           <td>apache.c</td>
           <td>[Apache]</td>
-          <td>&apache.c;</td>
+          <td><entity>&apache.c;</entity></td>
         </tr>
         <tr>
           <td>apache.d</td>
           <td>
-            &lt;a href=&quot;http://www.apache.org/&quot;&gt;&apache.b;&lt;/a&gt;
+            &lt;a href=&quot;http://www.apache.org/&quot;&gt;&lt;Apache&gt;&lt;/a&gt;
           </td>
-          <td>&apache.d;</td>
+          <td><entity>&apache.d;</entity></td>
         </tr>
         <tr>
           <td>apache.e</td>
-          <td><a href="http://www.apache.org/">&apache.b;</a></td>
-          <td>&apache.e;</td>
+          <td><a href="http://www.apache.org/">&lt;Apache&gt;</a></td>
+          <td><entity>&apache.e;</entity></td>
         </tr>
         <tr>
           <td>apache.f</td>
-          <td><em>&apache.a;</em></td>
-          <td>&apache.f;</td>
+          <td><em>Apache</em></td>
+          <td><entity>&apache.f;</entity></td>
         </tr>
       </table>
 
diff --git a/xdoc/xdocs/reference/xdocs.xml b/xdoc/xdocs/reference/xdocs.xml
index ad3a6b82..21369f4b 100644
--- a/xdoc/xdocs/reference/xdocs.xml
+++ b/xdoc/xdocs/reference/xdocs.xml
@@ -134,6 +134,37 @@
         </p>
       </subsection>
 
+      <subsection name="Custom entities">
+        <p>
+          Due to a bug in Jelly, it is not possible to use custom entities directly in xdoc documents.
+          A workaround has been implemented such that you need to embed your entities
+          in <code>&lt;entity&gt;</code> tags. First you should declare the resource file
+          for your entities:
+        </p>
+        <source><![CDATA[<?xml version="1.0"?>
+<!DOCTYPE document [
+  <!ENTITY % my-entities SYSTEM "entities.ent">
+  %my-entities;
+]>
+<document>
+...]]></source>
+        <p>
+          where the file <code>entities.ent</code> contains, eg:
+        </p>
+        <source><![CDATA[<!ENTITY version '1.3.2-SNAPSHOT'>]]></source>
+        <p>
+          which can then be used in your xdoc like:
+        </p>
+        <source><![CDATA[<p>
+  This information only applies to version <entity>&version;</entity>.
+</p>]]></source>
+        <p>
+          <strong>Note</strong> that xdoc files using entities in this way
+          cannot be validated with the <code>xdoc:validate</code> goal
+          (see below).
+        </p>
+      </subsection>
+
     </section>
 
     <section name="Validation">