diff --git a/examples/1ptracer/.doc_config b/examples/1ptracer/.doc_config
index fd0ffdb7e16e860fe8a4751b747e54d7f375fc5a..028f23fcd603caaf1bcf449b16e19f827a4f817f 100644
--- a/examples/1ptracer/.doc_config
+++ b/examples/1ptracer/.doc_config
@@ -1,7 +1,11 @@
-doc/intro.md
-spatialparams_1p.hh
-problem_1p.hh
-spatialparams_tracer.hh
-problem_tracer.hh
-main.cc
-doc/results.md
+{
+    "README.md" : [
+        "doc/intro.md",
+        "spatialparams_1p.hh",
+        "problem_1p.hh",
+        "spatialparams_tracer.hh",
+        "problem_tracer.hh",
+        "main.cc",
+        "doc/results.md"
+    ]
+}
diff --git a/examples/2pinfiltration/.doc_config b/examples/2pinfiltration/.doc_config
index fd1032cf1646c598af7f20dd3582d0e2eef1487c..bd7eeb8e44cfd7945055c33c726f894d5cb3a4ba 100644
--- a/examples/2pinfiltration/.doc_config
+++ b/examples/2pinfiltration/.doc_config
@@ -1,5 +1,9 @@
-doc/intro.md
-spatialparams.hh
-problem.hh
-main.cc
-doc/results.md
+{
+    "README.md" : [
+        "doc/intro.md",
+        "spatialparams.hh",
+        "problem.hh",
+        "main.cc",
+        "doc/results.md"
+    ]
+}
diff --git a/examples/freeflowchannel/.doc_config b/examples/freeflowchannel/.doc_config
index cf97091424913c537e2f1539c78d6a21469dabd6..09ab5781d75fc992eb1a8ac0d2448f34acd0b76c 100644
--- a/examples/freeflowchannel/.doc_config
+++ b/examples/freeflowchannel/.doc_config
@@ -1,4 +1,8 @@
-doc/intro.md
-problem.hh
-main.cc
-doc/results.md
+{
+    "README.md" : [
+        "doc/intro.md",
+        "problem.hh",
+        "main.cc",
+        "doc/results.md"
+    ]
+}
diff --git a/examples/generate_example_docs.py b/examples/generate_example_docs.py
index 908f9b360c24a24d671883e3e6c944cfdc86c3ee..c20f706be3f5b0d1b82ab548dccfb79ec273f465 100755
--- a/examples/generate_example_docs.py
+++ b/examples/generate_example_docs.py
@@ -1,43 +1,45 @@
 #!/usr/bin/env python3
 
 import os
+import json
 import argparse
 
 from convert_code_to_doc import *
 
-def convertToMarkdownAndMerge(dir, includeList):
-    with open(os.path.join(dir, "README.md"), "w") as readme:
-        for include, description in includeList:
-            fileExtension = os.path.splitext(include)[1]
-            if fileExtension == ".md":
-                with open(os.path.join(dir, include), "r") as markdown:
-                    readme.write(markdown.read())
-            elif fileExtension == ".hh" or fileExtension == ".cc":
-                title = description + " (`{}`)\n\n\n" if description else "The file `{}`\n\n\n"
-                title = title.format(os.path.split(include)[1])
-                readme.write("\n\n## " + title)
-                with open(os.path.join(dir, include), "r") as cppCode:
-                    readme.write(transformCode(cppCode.read(), cppRules()) + "\n")
-            else:
-                raise IOError("Unsupported or unknown file extension *{}".format(fileExtension))
+def convertToMarkdownAndMerge(dir, config):
+
+    for target, sources in config.items():
+
+        targetExtension = os.path.splitext(target)[1]
+        if not targetExtension == ".md":
+            raise IOError("Markdown files expected as targets! Given target: {}".format(target))
+
+        targetPath = os.path.join(dir, target)
+        os.makedirs(os.path.dirname(targetPath), exist_ok=True)
+
+        with open(targetPath, "w") as targetFile:
+            for source in sources:
+                fileExtension = os.path.splitext(source)[1]
+                if fileExtension == ".md":
+                    with open(os.path.join(dir, source), "r") as markdown:
+                        targetFile.write(markdown.read())
+                elif fileExtension == ".hh" or fileExtension == ".cc":
+                    with open(os.path.join(dir, source), "r") as cppCode:
+                        targetFile.write("\n\n" + transformCode(cppCode.read(), cppRules()) + "\n")
+                else:
+                    raise IOError("Unsupported or unknown file extension *{}".format(fileExtension))
 
 def generateReadme(dir):
-    includeList = None
+    config = None
     # look for .doc_config, if not found we pass
     try:
         configname = os.path.join(dir, ".doc_config")
-        with open(configname, 'r') as config:
-            def readline(line):
-                line = line.split(' ', 1)
-                if len(line) == 1:
-                    return [line[0], ""]
-                else:
-                    return [line[0], line[1]]
-            includeList = [readline(line) for line in config.read().splitlines()]
+        with open(configname, 'r') as configFile:
+            config = json.load(configFile)
     except FileNotFoundError:
         pass
-    if includeList is not None:
-        convertToMarkdownAndMerge(dir, includeList)
+    if config is not None:
+        convertToMarkdownAndMerge(dir, config)
 
 if __name__ == '__main__':
     parser = argparse.ArgumentParser()
diff --git a/examples/shallowwaterfriction/.doc_config b/examples/shallowwaterfriction/.doc_config
index fd1032cf1646c598af7f20dd3582d0e2eef1487c..bd7eeb8e44cfd7945055c33c726f894d5cb3a4ba 100644
--- a/examples/shallowwaterfriction/.doc_config
+++ b/examples/shallowwaterfriction/.doc_config
@@ -1,5 +1,9 @@
-doc/intro.md
-spatialparams.hh
-problem.hh
-main.cc
-doc/results.md
+{
+    "README.md" : [
+        "doc/intro.md",
+        "spatialparams.hh",
+        "problem.hh",
+        "main.cc",
+        "doc/results.md"
+    ]
+}