diff --git a/docs/_includes/custom/xpath_fun_doc.html b/docs/_includes/custom/xpath_fun_doc.html
index 5865e37f0e..12a7781adf 100644
--- a/docs/_includes/custom/xpath_fun_doc.html
+++ b/docs/_includes/custom/xpath_fun_doc.html
@@ -38,7 +38,9 @@
 
                     <div style="margin-left: 15px" class="xpath-fun-doc">
 
-                        <h4 class="fun-details-header">
+                        <!-- Yeah the ID is duplicated but it's ok on my browser and makes -->
+                        <!--links somehow work when details are collapsed -->
+                        <h4 class="fun-details-header" id="{{ fun_id }}">
                             <span class="fun-ns">{{ lang.ns | append: ':' }}</span><span
                                 class="fun-name">{{ fun.name }}</span><span
                                 class="fun-ns">{{ fun | xpath_fun_type }}</span>
@@ -47,26 +49,24 @@
                         <div style="margin-left: 30px">
 
                             <dl>
-                                <dd>{{ fun.description }}</dd>
+                                <dd>{{ fun.description | render_markdown }}</dd>
                                 <dt>Remarks</dt>
-                                <dd>{{ fun.notes }}</dd>
+                                <dd>{{ fun.notes | render_markdown }}</dd>
 
                                 {% if fun.parameters.size > 0 %}
 
                                 <dt>Parameters</dt>
 
                                 <dd>
-                                    <div style="margin-left: 20px">
-                                        <dl>
-                                            {% for param in fun.parameters %}
-                                            <dt>
-                                                <span class="param-name">{{ param.name }}</span>
-                                                <span class="param-type"> as {{ param.type }}</span>
-                                            </dt>
-                                            <dd>{{ param.description }}</dd>
-                                            {% endfor %}
-                                        </dl>
-                                    </div>
+                                    <dl>
+                                        {% for param in fun.parameters %}
+                                        <dt>
+                                            <span class="param-name">{{ param.name }}</span>
+                                            <span class="param-type"> as {{ param.type }}</span>
+                                        </dt>
+                                        <dd>{{ param.description | render_markdown }}</dd>
+                                        {% endfor %}
+                                    </dl>
                                 </dd>
 
                                 {% endif %}
@@ -76,14 +76,12 @@
                                 <dt>Examples</dt>
 
                                 <dd>
-                                    <div style="margin-left: 20px">
-                                        <dl class="code-examples">
-                                            {% for example in fun.examples %}
-                                            <dt><code>{{ example.code }}</code></dt>
-                                            <dd>{% render %}{{ example.outcome }}{%endrender%}</dd>
-                                            {% endfor %}
-                                        </dl>
-                                    </div>
+                                    <dl class="code-examples">
+                                        {% for example in fun.examples %}
+                                        <dt><code>{{ example.code }}</code></dt>
+                                        <dd>{{ example.outcome | render_markdown }}</dd>
+                                        {% endfor %}
+                                    </dl>
                                 </dd>
                                 {% endif %}
                             </dl>
diff --git a/docs/_plugins/custom_filters.rb b/docs/_plugins/custom_filters.rb
index 2b3067e21a..c3cdec7a0a 100644
--- a/docs/_plugins/custom_filters.rb
+++ b/docs/_plugins/custom_filters.rb
@@ -1,3 +1,5 @@
+require 'kramdown'
+
 module CustomFilters
 
   # set intersection
@@ -44,6 +46,10 @@ module CustomFilters
 
   end
 
+  def render_markdown(text)
+    Kramdown::Document.new(text).to_html
+  end
+
   def xpath_fun_type(fun_yaml)
 
     res = '('