diff --git a/xdoc/src/plugin-resources/site.jsl b/xdoc/src/plugin-resources/site.jsl
index ffa28c46..4adfed34 100644
--- a/xdoc/src/plugin-resources/site.jsl
+++ b/xdoc/src/plugin-resources/site.jsl
@@ -453,7 +453,8 @@
   <jsl:template match="section" trim="true">
     <div class="section">
       <x:set var="_sectionName" select="string(@name)"/>
-      
+      <j:set var="_sectionId"><x:expr select="@id"/></j:set>
+
       <!-- Key is more important than message... -->
       <j:set var="_key">
         <x:expr select="@key" />
@@ -473,11 +474,18 @@
         </j:if>
       </j:if>
 
-      <!-- named anchors can't contain whitespaces -->
-      <j:set var="_anchorName"><doc:escapeNameToken value="${_sectionName}"/></j:set>
-      <j:if test="${!empty(_sectionName)}">
-          <a name="${_anchorName}"/><h2>${_sectionName}</h2>
+      <!-- construct anchor from 'id' tag if it exists, from 'name' tag otherwise -->
+      <j:if test="${!empty(_sectionId)}">
+        <j:set var="_anchorName"><x:expr select="@id"/></j:set>
+       </j:if>
+       <j:if test="${empty(_sectionId)}">
+        <!-- named anchors can't contain whitespaces -->
+        <j:set var="_anchorName"><doc:escapeNameToken value="${_sectionName}"/></j:set>
       </j:if>
+      <j:if test="${!empty(_anchorName)}">
+        <a name="${_anchorName}"/>
+      </j:if>
+      <h2>${_sectionName}</h2>
       <jsl:applyTemplates />
     </div>
   </jsl:template>
@@ -485,7 +493,8 @@
   <jsl:template match="subsection" trim="true">
     <div class="subsection">
       <x:set var="_sectionName" select="string(@name)"/>
-      
+      <j:set var="_sectionId"><x:expr select="@id"/></j:set>
+
       <!-- Key is more important than message... -->
       <j:set var="_key">
         <x:expr select="@key" />
@@ -504,12 +513,19 @@
           </fmt:bundle>
         </j:if>
       </j:if>
-      
-      <!-- named anchors can't contain whitespaces -->
-      <j:set var="_anchorName"><doc:escapeNameToken value="${_sectionName}"/></j:set>
-      <j:if test="${!empty(_sectionName)}">
-          <a name="${_anchorName}"/><h3>${_sectionName}</h3>
+
+      <!-- construct anchor from 'id' tag if it exists, from 'name' tag otherwise -->
+      <j:if test="${!empty(_sectionId)}">
+        <j:set var="_anchorName"><x:expr select="@id"/></j:set>
+       </j:if>
+      <j:if test="${empty(_sectionId)}">
+        <!-- named anchors can't contain whitespaces -->
+        <j:set var="_anchorName"><doc:escapeNameToken value="${_sectionName}"/></j:set>
       </j:if>
+      <j:if test="${!empty(_anchorName)}">
+        <a name="${_anchorName}"/>
+      </j:if>
+      <h3>${_sectionName}</h3>
       <jsl:applyTemplates />
     </div>
   </jsl:template>
diff --git a/xdoc/xdocs/changes.xml b/xdoc/xdocs/changes.xml
index 9919e619..68d3c5b8 100644
--- a/xdoc/xdocs/changes.xml
+++ b/xdoc/xdocs/changes.xml
@@ -27,6 +27,7 @@
   </properties>
   <body>
     <release version="1.10" date="in SVN">
+      <action dev="ltheussl" type="add" issue="MPXDOC-158">Add an optional id tag to sub/sections, so they can be referenced.</action>
       <action dev="ltheussl" type="add" issue="MPXDOC-144">Add a property to override <code>navigation.xml</code>.</action>
       <action dev="ltheussl" type="add" issue="MPXDOC-127" due-to="Shinobu Kawai Yoshida">Show organization in header even if logo not set.</action>
       <action dev="ltheussl" type="fix" issue="MPXDOC-47">Ampersands in navigation.xml being escaped twice.</action>
diff --git a/xdoc/xdocs/index.xml b/xdoc/xdocs/index.xml
index 7a681447..f1aae2b4 100644
--- a/xdoc/xdocs/index.xml
+++ b/xdoc/xdocs/index.xml
@@ -74,6 +74,47 @@
       <subsection name="External Link Icon">
         <p>XDoc automatically adds the "External Link" icon and tooltip to links referring to external sites (actually, any absolute url).</p>
       </subsection>
+      <subsection name="Referencing sections and subsections">
+        <p>
+          From version <code>1.10</code> on, the <code>xdoc</code> plugin
+          allows for an optional <code>id</code> tag in the <code>section</code>
+          and <code>subsection</code> elements:
+        </p>
+        <source><![CDATA[<section name="Section" id="Section1">
+    <subsection name="SubSection" id="SubSection1">
+    </subsection>
+</section>]]></source>
+        <p>
+          An anchor is constructed from each <code>id</code> tag,
+          so you can reference sections and subsections from other source
+          documents. Note that each <code>id</code> tag has to be unique
+          within one source document.
+        </p>
+        <p>
+          In previous versions of the plugin, an <code>id</code> tag
+          was constructed from section/subsection names, replacing special
+          characters by underscores. For backwards compatibility reasons,
+          we keep this behaviour, <emph>i.e.</emph>, if no <code>id</code> tag
+          is present, an anchor is constructed from the <code>name</code> tag.
+          Note that this presents two shortcomings:
+        </p>
+        <ul>
+          <li>
+            If two sections or subsections have identical names
+            (within one source document), you will get an ambiguity when
+            referencing them. Also the resulting html document will not be
+            valid XHTML.
+          </li>
+          <li>
+            For long section titles, this leads to rather
+            cumbersome anchor names.
+          </li>
+        </ul>
+        <p>
+          We recommend that you provide an <code>id</code> tag if you
+          want to reference a section or subsection.
+        </p>
+      </subsection>
     </section>
   </body>
 </document>
