diff --git a/.markdownlint.yml b/.markdownlint.yml
index b59a114..da116c7 100644
--- a/.markdownlint.yml
+++ b/.markdownlint.yml
@@ -2,5 +2,6 @@
 default: True
 MD013: False
 MD041: False
+MD024: False
 MD004:
   style: dash
diff --git a/ansibledoctor/doc_generator.py b/ansibledoctor/doc_generator.py
index 9997c19..189cba0 100644
--- a/ansibledoctor/doc_generator.py
+++ b/ansibledoctor/doc_generator.py
@@ -119,7 +119,9 @@ class Generator:
                             )
                             jenv.filters["to_nice_yaml"] = self._to_nice_yaml
                             jenv.filters["deep_get"] = self._deep_get
-                            jenv.filters["save_join"] = self._save_join
+                            jenv.filters["safe_join"] = self._safe_join
+                            # keep the old name of the function to not break custom templates.
+                            jenv.filters["save_join"] = self._safe_join
                             data = jenv.from_string(data).render(role_data, role=role_data)
                             if not self.config.config["dry_run"]:
                                 with open(doc_file, "wb") as outfile:
@@ -129,7 +131,9 @@ class Generator:
                             else:
                                 self.logger.info(f"Writing to: {doc_file}")
                         except (
-                            jinja2.exceptions.UndefinedError, jinja2.exceptions.TemplateSyntaxError
+                            jinja2.exceptions.UndefinedError,
+                            jinja2.exceptions.TemplateSyntaxError,
+                            jinja2.exceptions.TemplateRuntimeError
                         ) as e:
                             self.log.sysexit_with_message(
                                 "Jinja2 templating error while loading file: '{}'\n{}".format(
@@ -157,7 +161,7 @@ class Generator:
         )
 
     @pass_eval_context
-    def _save_join(self, eval_ctx, value, d=""):
+    def _safe_join(self, eval_ctx, value, d=""):
         if isinstance(value, str):
             value = [value]
 
diff --git a/ansibledoctor/templates/hugo-book/_tag.j2 b/ansibledoctor/templates/hugo-book/_tag.j2
index a42f1c0..3a5bee4 100644
--- a/ansibledoctor/templates/hugo-book/_tag.j2
+++ b/ansibledoctor/templates/hugo-book/_tag.j2
@@ -4,8 +4,8 @@
 {% for key, item in tag | dictsort %}
 
 {{ key }}
-{% if item.description is defined and item.description | save_join(" ") | striptags %}
-: {{ item.description | save_join(" ") | striptags }}
+{% if item.description is defined and item.description | safe_join(" ") | striptags %}
+: {{ item.description | safe_join(" ") | striptags }}
 {% else %}
 :  
 {% endif %}
diff --git a/ansibledoctor/templates/hugo-book/_todo.j2 b/ansibledoctor/templates/hugo-book/_todo.j2
index 6bbee86..679deb9 100644
--- a/ansibledoctor/templates/hugo-book/_todo.j2
+++ b/ansibledoctor/templates/hugo-book/_todo.j2
@@ -4,15 +4,15 @@
 
 {% for key, item in todo | dictsort %}
 {% for line in item %}
-{% if line.value is defined and line.value | save_join(" ") | striptags and key == "default" %}
-- {{ line.value | save_join(" ") | striptags }}
+{% if line.value is defined and line.value | safe_join(" ") | striptags and key == "default" %}
+- {{ line.value | safe_join(" ") | striptags }}
 {% endif %}
 {% endfor %}
 {% endfor %}
 {% for key, item in todo | dictsort %}
 {% for line in item %}
-{% if line.value is defined and line.value | save_join(" ") | striptags and key != "default" %}
-- ({{ key }}): {{ line.value | save_join(" ") | striptags }}
+{% if line.value is defined and line.value | safe_join(" ") | striptags and key != "default" %}
+- ({{ key }}): {{ line.value | safe_join(" ") | striptags }}
 {% endif %}
 {% endfor %}
 {% endfor %}
diff --git a/ansibledoctor/templates/hugo-book/_vars.j2 b/ansibledoctor/templates/hugo-book/_vars.j2
index 323addf..f823ec1 100644
--- a/ansibledoctor/templates/hugo-book/_vars.j2
+++ b/ansibledoctor/templates/hugo-book/_vars.j2
@@ -7,7 +7,7 @@
 ### {{ key }}
 {% if item.description is defined and item.description %}
 
-{{ item.description | save_join(" ") }}
+{{ item.description | map("replace", "\n\n", "\n") | safe_join("\n") }}
 {% endif %}
 {% if item.value is defined and item.value %}
 
diff --git a/ansibledoctor/templates/hugo-book/index.md.j2 b/ansibledoctor/templates/hugo-book/index.md.j2
index caee70a..94dc9e9 100644
--- a/ansibledoctor/templates/hugo-book/index.md.j2
+++ b/ansibledoctor/templates/hugo-book/index.md.j2
@@ -1,16 +1,16 @@
 {% if not append | deep_get(role, "internal.append") %}
 {% set meta = role.meta | default({}) %}
 ---
-title: {{ meta.name.value | save_join(" ") }}
+title: {{ meta.name.value | safe_join(" ") }}
 type: docs
 {% if summary | deep_get(meta, "summary.value") %}
-summary: {{ meta.summary.value | save_join(" ") }}
+summary: {{ meta.summary.value | safe_join(" ") }}
 {% endif %}
 ---
 {% endif %}
 {% if description | deep_get(meta, "description.value") %}
 
-{{ meta.description.value | save_join(" ") }}
+{{ meta.description.value | map("replace", "\n\n", "\n") | safe_join("\n") }}
 {% endif %}
 
 <!--more-->
diff --git a/ansibledoctor/templates/readme/README.md.j2 b/ansibledoctor/templates/readme/README.md.j2
index 0fecd44..9bf5dd4 100644
--- a/ansibledoctor/templates/readme/README.md.j2
+++ b/ansibledoctor/templates/readme/README.md.j2
@@ -1,10 +1,10 @@
 {% if not append | deep_get(role, "internal.append") %}
 {% set meta = role.meta | default({}) %}
-# {{ meta.name.value | save_join(" ") }}
+# {{ meta.name.value | safe_join(" ") }}
 {% endif %}
 {% if description | deep_get(meta, "description.value") %}
 
-{{ meta.description.value | save_join(" ") }}
+{{ meta.description.value | map("replace", "\n\n", "\n") | safe_join("\n") }}
 {% endif %}
 
 {#      TOC      #}
diff --git a/ansibledoctor/templates/readme/_meta.j2 b/ansibledoctor/templates/readme/_meta.j2
index c2fc1a3..df7c77e 100644
--- a/ansibledoctor/templates/readme/_meta.j2
+++ b/ansibledoctor/templates/readme/_meta.j2
@@ -26,6 +26,6 @@ None.
 
 ## Author
 
-{{ meta.author.value | save_join(" ") }}
+{{ meta.author.value | safe_join(" ") }}
 {% endif %}
 {% endif %}
diff --git a/ansibledoctor/templates/readme/_tag.j2 b/ansibledoctor/templates/readme/_tag.j2
index 681c97c..04c32f6 100644
--- a/ansibledoctor/templates/readme/_tag.j2
+++ b/ansibledoctor/templates/readme/_tag.j2
@@ -2,11 +2,11 @@
 {% if tag %}
 ## Discovered Tags
 {% for key, item in tag | dictsort %}
-{% set is_desc = item.description is defined and item.description | save_join(" ") | striptags %}
+{% set is_desc = item.description is defined and item.description | safe_join(" ") | striptags %}
 
 **_{{ key }}_**{{ "\\" if is_desc else "" }}
 {% if is_desc %}
-&emsp;{{ item.description | save_join(" ") | striptags }}
+&emsp;{{ item.description | safe_join(" ") | striptags }}
 {% endif %}
 {% endfor %}
 {% endif %}
diff --git a/ansibledoctor/templates/readme/_todo.j2 b/ansibledoctor/templates/readme/_todo.j2
index 6bbee86..679deb9 100644
--- a/ansibledoctor/templates/readme/_todo.j2
+++ b/ansibledoctor/templates/readme/_todo.j2
@@ -4,15 +4,15 @@
 
 {% for key, item in todo | dictsort %}
 {% for line in item %}
-{% if line.value is defined and line.value | save_join(" ") | striptags and key == "default" %}
-- {{ line.value | save_join(" ") | striptags }}
+{% if line.value is defined and line.value | safe_join(" ") | striptags and key == "default" %}
+- {{ line.value | safe_join(" ") | striptags }}
 {% endif %}
 {% endfor %}
 {% endfor %}
 {% for key, item in todo | dictsort %}
 {% for line in item %}
-{% if line.value is defined and line.value | save_join(" ") | striptags and key != "default" %}
-- ({{ key }}): {{ line.value | save_join(" ") | striptags }}
+{% if line.value is defined and line.value | safe_join(" ") | striptags and key != "default" %}
+- ({{ key }}): {{ line.value | safe_join(" ") | striptags }}
 {% endif %}
 {% endfor %}
 {% endfor %}
diff --git a/ansibledoctor/templates/readme/_vars.j2 b/ansibledoctor/templates/readme/_vars.j2
index 323addf..f823ec1 100644
--- a/ansibledoctor/templates/readme/_vars.j2
+++ b/ansibledoctor/templates/readme/_vars.j2
@@ -7,7 +7,7 @@
 ### {{ key }}
 {% if item.description is defined and item.description %}
 
-{{ item.description | save_join(" ") }}
+{{ item.description | map("replace", "\n\n", "\n") | safe_join("\n") }}
 {% endif %}
 {% if item.value is defined and item.value %}
 
diff --git a/example/README.md b/example/README.md
index 8015143..fbe3e98 100644
--- a/example/README.md
+++ b/example/README.md
@@ -3,7 +3,8 @@
 [![Build Status](https://img.shields.io/drone/build/thegeeklab/ansible-doctor?logo=drone&server=https%3A%2F%2Fdrone.thegeeklab.de)](https://drone.thegeeklab.de/thegeeklab/ansible-doctor)
 [![License: GPL-3.0](https://img.shields.io/github/license/thegeeklab/ansible-doctor)](https://github.com/thegeeklab/ansible-doctor/blob/main/LICENSE)
 
-Role to demonstrate ansible-doctor. It is also possible to overwrite the default description with an annotation.
+Role to demonstrate ansible-doctor. It is also possible to overwrite
+the default description with an annotation.
 
 ## Table of content
 
@@ -61,7 +62,8 @@ demo_role_empty: ''
 
 ### demo_role_empty_dict
 
-... or valid json can be used. In this case, the json will be automatically prefixed with the annotation key and filters like `to_nice_yaml` can be used in templates. To get it working, the json need to be prefixed with a `$`.
+... or valid json can be used. In this case, the json will be automatically prefixed with the annotation key
+and filters like `to_nice_yaml` can be used in templates. To get it working, the json need to be prefixed with a `$`.
 
 #### Default value
 
@@ -127,7 +129,12 @@ demo_role_single: b
 
 ### demo_role_undefined_var
 
-To highlight a variable that has not set a value by default, this is one way to achieve it. Make sure to flag it as json value: `@var demo_role_undefined_var: $ "_unset_"`
+To highlight a variable that has not set a value by default, this is one way to achieve it.
+Make sure to flag it as json value: `@var demo_role_undefined_var: $ "_unset_"`
+
+| Attribute | Description |
+| --- | --- |
+| value1 | desc1 |
 
 #### Default value
 
diff --git a/example/demo-role/defaults/main.yml b/example/demo-role/defaults/main.yml
index 212fab1..c7ef05d 100644
--- a/example/demo-role/defaults/main.yml
+++ b/example/demo-role/defaults/main.yml
@@ -31,6 +31,11 @@ demo_role_dict:
 # @var demo_role_undefined_var:description: >
 # To highlight a variable that has not set a value by default, this is one way to achieve it.
 # Make sure to flag it as json value: `@var demo_role_undefined_var: $ "_unset_"`
+#
+# | Attribute | Description |
+# | --- | --- |
+# | value1 | desc1 |
+#
 # @end
 # @var demo_role_undefined_var: $ "_unset_"