diff --git a/unittests/test_macros.py b/unittests/test_macros.py
index 7ac34cc7c48df3cb2855d7022119e4775d90c9a6..7cbb08ed85a57cd11bb04203d567ff060909376e 100644
--- a/unittests/test_macros.py
+++ b/unittests/test_macros.py
@@ -53,6 +53,7 @@ def _temp_file_load(txt: str):
         f.write(txt.encode())
         f.flush()
         c = Crawler()
+        print(txt)
         definition = c.load_definition(f.name)
     return definition
 
@@ -295,7 +296,6 @@ extroot3: !macro
     assert cfood["extroot3"]["test_four"] is None
 
 
-# @pytest.mark.xfail(reason="Fix multiple usage of the same macro.")
 def test_use_macro_twice():
     """Test that the same macro can be used twice with different parameters in
     the same CFood element if the name depends on the parameters.
@@ -328,3 +328,86 @@ extroot: !macro
     assert cfood["extroot"]["once"]["something"]["a"] == "4"
     assert cfood["extroot"]["twice"]["something"]["a"] == "5"
     assert cfood["extroot"]["default_name"]["something"]["a"] == "4"
+
+    # Code sample to generate the expanded macro:
+    # with open("expanded_test_macro.yaml", "w") as f:
+    #     f.write(yaml.dump(cfood))
+
+
+def test_documentation_example_2():
+
+    cfood = _temp_file_load("""
+---
+metadata:
+  macros:
+  - !defmacro
+    name: MarkdownFile
+    params:
+      name: null
+      filename: null
+    definition:
+      ${name}_filename:
+        type: SimpleFile
+        match: $filename
+        records:
+          $name:
+            parents:
+            - MarkdownFile
+            role: File
+            path: ${name}_filename
+            file: ${name}_filename
+---
+ExperimentalData:
+  type: Directory
+  match: ExperimentalData
+  subtree: !macro
+    MarkdownFile:
+    - name: README
+      filename: ^README.md$
+    """)
+
+    # Code sample to generate the expanded macro:
+    # with open("expanded_test_macro.yaml", "w") as f:
+    #     f.write(yaml.dump(cfood))
+
+
+def test_documentation_example_1():
+
+    cfood = _temp_file_load("""
+---
+metadata:
+  macros:
+  - !defmacro
+    name: SimulationDatasetFile
+    params:
+      match: null
+      recordtype: null
+      nodename: null
+    definition:
+      $nodename:
+        match: $match
+        type: SimpleFile
+        records:
+          File:
+            parents:
+            - $recordtype
+            role: File
+            path: $$$nodename
+            file: $$$nodename
+          Simulation:
+            $recordtype: +$File
+---
+SimulationData:
+  type: Directory
+  match: SimulationData
+  subtree: !macro
+    SimulationDatasetFile:
+    - match: .*
+      recordtype: DatasetFile
+      nodename: Dataset
+    """)
+
+    # Code sample to generate the expanded macro:
+    # with open("expanded_test_macro.yaml", "w") as f:
+    #     f.write(yaml.dump(cfood))
+