diff --git a/.gitignore b/.gitignore
index 9783918..ba98727 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,5 @@ htmlcov
 .coverage
 coverage.xml
 dist
+
+.venv
diff --git a/aar_doc/templates/markdown.j2 b/aar_doc/templates/markdown.j2
index d5cebe2..cf5c3d6 100644
--- a/aar_doc/templates/markdown.j2
+++ b/aar_doc/templates/markdown.j2
@@ -1,5 +1,5 @@
 # Ansible Role: {{ role }}
----
+
 {%- if "version" in galaxy_collection %}
 Version: {{ galaxy_collection.version }}
 {% endif %}
@@ -9,7 +9,7 @@ Tags: {{ metadata.galaxy_info.galaxy_tags | join(', ') }}
 {%- endif %}
 
 ## Requirements
----
+
 | Platform | Versions |
 | -------- | -------- |
 {%- for platform in metadata.galaxy_info.platforms %}
@@ -17,11 +17,11 @@ Tags: {{ metadata.galaxy_info.galaxy_tags | join(', ') }}
 {%- endfor %}
 
 ## Role Arguments
----
+
 {% for entrypoint in argument_specs.keys() %}
 
 ### Entrypoint: {{ entrypoint }}
----
+
 {{ argument_specs[entrypoint].short_description }}
 
 {% if entrypoint_options[entrypoint] %}
@@ -35,7 +35,7 @@ Tags: {{ metadata.galaxy_info.galaxy_tags | join(', ') }}
 {% if entrypoint_options[entrypoint] | length > 1 -%}
 {% for path, options in entrypoint_options[entrypoint][1:] -%}
 #### Options for {{ path | join(" > ") }}
----
+
 |Option|Description|Type|Required|Default|
 |---|---|---|---|---|
 {%- for name, details in options.items() %}
@@ -45,10 +45,11 @@ Tags: {{ metadata.galaxy_info.galaxy_tags | join(', ') }}
 {% endfor -%}
 
 {% endif -%}
+
 {% if entrypoint in entrypoint_choices -%}
 {% for path, choices in entrypoint_choices[entrypoint] -%}
 #### Choices for {{ path | join(" > ") }}
----
+
 |Choice|
 |---|
 {%- for item in choices %}
@@ -63,10 +64,17 @@ This entrypoint has no options.
 
 {% endif -%}
 
+{%- if "examples" in argument_specs[entrypoint] -%}
+
+#### Examples
+
+{{ argument_specs[entrypoint].examples }}
+
+{%- endif -%}
 {% endfor %}
 
 ## Dependencies
----
+
 {%- if ("dependencies" in metadata) and (metadata.dependencies | length > 0) %}
 {%- for dependency in metadata.dependencies %}
 - {{ dependency }}
@@ -76,7 +84,7 @@ None.
 {%- endif %}
 
 ## Example Playbook
----
+
 ```
 - hosts: all
   tasks:
@@ -97,11 +105,11 @@ None.
 ```
 
 ## License
----
+
 {{ metadata.galaxy_info.license }}
 
 ## Author and Project Information
----
+
 {%- if "company" in metadata.galaxy_info %}
 {{ metadata.galaxy_info.author }} @ {{ metadata.galaxy_info.company }}
 {%- else %}
diff --git a/tests/fixtures/roles/extended/README.md b/tests/fixtures/roles/extended/README.md
index 73fbefd..fcf10be 100644
--- a/tests/fixtures/roles/extended/README.md
+++ b/tests/fixtures/roles/extended/README.md
@@ -1,12 +1,11 @@
 <!-- BEGIN_ANSIBLE_DOCS -->
 # Ansible Role: extended
----
 Test role with lots of metadata
 
 Tags: ansible, docs
 
 ## Requirements
----
+
 | Platform | Versions |
 | -------- | -------- |
 | Fedora | all |
@@ -14,11 +13,11 @@ Tags: ansible, docs
 | Cumulus | 2.5 |
 
 ## Role Arguments
----
+
 
 
 ### Entrypoint: main
----
+
 The main entrypoint for the extended role
 
 |Option|Description|Type|Required|Default|
@@ -31,7 +30,7 @@ The main entrypoint for the extended role
 | default_type | Type is str by default | str | no |  |
 
 #### Choices for main > choices-str
----
+
 |Choice|
 |---|
 | one |
@@ -39,17 +38,24 @@ The main entrypoint for the extended role
 | three |
 
 #### Choices for main > choices-int
----
+
 |Choice|
 |---|
 | 1 |
 | 8 |
 | 42 |
 
+#### Examples
+
+this is an example how to execute the entrypoint:
+
+    - hosts: all
+      roles:
+        - extended
 
 
 ### Entrypoint: list
----
+
 The list entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -61,7 +67,7 @@ The list entry point for the extended role.
 
 
 ### Entrypoint: dict
----
+
 The dict entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -71,7 +77,7 @@ The dict entry point for the extended role.
 
 
 ### Entrypoint: dict-with-options
----
+
 The dict-with-options entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -79,7 +85,7 @@ The dict-with-options entry point for the extended role.
 | opts | A dictionary of keys and values | dict of 'opts' options | no |  |
 
 #### Options for dict-with-options > opts
----
+
 |Option|Description|Type|Required|Default|
 |---|---|---|---|---|
 | int | An int value | int | no | 1 |
@@ -87,7 +93,7 @@ The dict-with-options entry point for the extended role.
 | subopts | A sub-dictionary of keys and values | dict of 'subopts' options | no |  |
 
 #### Options for dict-with-options > opts > subopts
----
+
 |Option|Description|Type|Required|Default|
 |---|---|---|---|---|
 | str | A str value | str | no |  |
@@ -95,7 +101,7 @@ The dict-with-options entry point for the extended role.
 
 
 ### Entrypoint: bool
----
+
 The bool entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -108,7 +114,7 @@ The bool entry point for the extended role.
 
 
 ### Entrypoint: int
----
+
 The int entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -118,7 +124,7 @@ The int entry point for the extended role.
 
 
 ### Entrypoint: float
----
+
 The float entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -128,7 +134,7 @@ The float entry point for the extended role.
 
 
 ### Entrypoint: path
----
+
 The path entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -138,7 +144,7 @@ The path entry point for the extended role.
 
 
 ### Entrypoint: raw
----
+
 The raw entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -149,7 +155,7 @@ The raw entry point for the extended role.
 
 
 ### Entrypoint: jsonarg
----
+
 The jsonarg entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -159,7 +165,7 @@ The jsonarg entry point for the extended role.
 
 
 ### Entrypoint: json
----
+
 The json entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -169,7 +175,7 @@ The json entry point for the extended role.
 
 
 ### Entrypoint: bytes
----
+
 The bytes entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -179,7 +185,7 @@ The bytes entry point for the extended role.
 
 
 ### Entrypoint: bits
----
+
 The bits entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -189,11 +195,10 @@ The bits entry point for the extended role.
 
 
 ## Dependencies
----
 None.
 
 ## Example Playbook
----
+
 ```
 - hosts: all
   tasks:
@@ -205,11 +210,10 @@ None.
 ```
 
 ## License
----
+
 MIT
 
 ## Author and Project Information
----
 your name @ ansible-docs
 
 Issues: [tracker](https://gitlab.com/kankare/ansible-docs/-/issues)
diff --git a/tests/fixtures/roles/extended/meta/argument_specs.yml b/tests/fixtures/roles/extended/meta/argument_specs.yml
index 62cd032..731505c 100644
--- a/tests/fixtures/roles/extended/meta/argument_specs.yml
+++ b/tests/fixtures/roles/extended/meta/argument_specs.yml
@@ -11,6 +11,12 @@ argument_specs:
     author:
       - Foo
       - Bar
+    examples: |
+      this is an example how to execute the entrypoint:
+
+          - hosts: all
+            roles:
+              - extended
     options:
       name:
         option-name: override
diff --git a/tests/fixtures/roles/inject/README.md b/tests/fixtures/roles/inject/README.md
index 0c5f7b4..72faac3 100644
--- a/tests/fixtures/roles/inject/README.md
+++ b/tests/fixtures/roles/inject/README.md
@@ -1,21 +1,20 @@
 <!-- BEGIN_ANSIBLE_DOCS -->
 # Ansible Role: inject
----
 Test role with some header and footer text outside of the template
 
 
 ## Requirements
----
+
 | Platform | Versions |
 | -------- | -------- |
 | Fedora | all |
 
 ## Role Arguments
----
+
 
 
 ### Entrypoint: main
----
+
 The main entry point for the minimum role.
 
 |Option|Description|Type|Required|Default|
@@ -26,11 +25,10 @@ The main entry point for the minimum role.
 
 
 ## Dependencies
----
 None.
 
 ## Example Playbook
----
+
 ```
 - hosts: all
   tasks:
@@ -42,11 +40,10 @@ None.
 ```
 
 ## License
----
+
 MIT
 
 ## Author and Project Information
----
 your name @ ansible-docs
 
 <!-- END_ANSIBLE_DOCS -->
diff --git a/tests/fixtures/roles/meta_main_yaml/README.md b/tests/fixtures/roles/meta_main_yaml/README.md
index 95dce63..76552ba 100644
--- a/tests/fixtures/roles/meta_main_yaml/README.md
+++ b/tests/fixtures/roles/meta_main_yaml/README.md
@@ -1,21 +1,20 @@
 <!-- BEGIN_ANSIBLE_DOCS -->
 # Ansible Role: meta_main_yaml
----
 Test role with a minimum amount of metadata
 
 
 ## Requirements
----
+
 | Platform | Versions |
 | -------- | -------- |
 | Fedora | all |
 
 ## Role Arguments
----
+
 
 
 ### Entrypoint: main
----
+
 The main entrypoint for the extended role
 
 |Option|Description|Type|Required|Default|
@@ -28,7 +27,7 @@ The main entrypoint for the extended role
 | default_type | Type is str by default | str | no |  |
 
 #### Choices for main > choices-str
----
+
 |Choice|
 |---|
 | one |
@@ -36,7 +35,7 @@ The main entrypoint for the extended role
 | three |
 
 #### Choices for main > choices-int
----
+
 |Choice|
 |---|
 | 1 |
@@ -46,7 +45,7 @@ The main entrypoint for the extended role
 
 
 ### Entrypoint: list
----
+
 The list entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -58,7 +57,7 @@ The list entry point for the extended role.
 
 
 ### Entrypoint: dict
----
+
 The dict entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -68,7 +67,7 @@ The dict entry point for the extended role.
 
 
 ### Entrypoint: dict-with-options
----
+
 The dict-with-options entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -76,7 +75,7 @@ The dict-with-options entry point for the extended role.
 | opts | A dictionary of keys and values | dict of 'opts' options | no |  |
 
 #### Options for dict-with-options > opts
----
+
 |Option|Description|Type|Required|Default|
 |---|---|---|---|---|
 | int | An int value | int | no | 1 |
@@ -84,7 +83,7 @@ The dict-with-options entry point for the extended role.
 | subopts | A sub-dictionary of keys and values | dict of 'subopts' options | no |  |
 
 #### Options for dict-with-options > opts > subopts
----
+
 |Option|Description|Type|Required|Default|
 |---|---|---|---|---|
 | str | A str value | str | no |  |
@@ -92,7 +91,7 @@ The dict-with-options entry point for the extended role.
 
 
 ### Entrypoint: bool
----
+
 The bool entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -105,7 +104,7 @@ The bool entry point for the extended role.
 
 
 ### Entrypoint: int
----
+
 The int entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -115,7 +114,7 @@ The int entry point for the extended role.
 
 
 ### Entrypoint: float
----
+
 The float entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -125,7 +124,7 @@ The float entry point for the extended role.
 
 
 ### Entrypoint: path
----
+
 The path entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -135,7 +134,7 @@ The path entry point for the extended role.
 
 
 ### Entrypoint: raw
----
+
 The raw entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -146,7 +145,7 @@ The raw entry point for the extended role.
 
 
 ### Entrypoint: jsonarg
----
+
 The jsonarg entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -156,7 +155,7 @@ The jsonarg entry point for the extended role.
 
 
 ### Entrypoint: json
----
+
 The json entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -166,7 +165,7 @@ The json entry point for the extended role.
 
 
 ### Entrypoint: bytes
----
+
 The bytes entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -176,7 +175,7 @@ The bytes entry point for the extended role.
 
 
 ### Entrypoint: bits
----
+
 The bits entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -186,11 +185,10 @@ The bits entry point for the extended role.
 
 
 ## Dependencies
----
 None.
 
 ## Example Playbook
----
+
 ```
 - hosts: all
   tasks:
@@ -202,11 +200,10 @@ None.
 ```
 
 ## License
----
+
 MIT
 
 ## Author and Project Information
----
 your name @ ansible-docs
 
 <!-- END_ANSIBLE_DOCS -->
diff --git a/tests/fixtures/roles/minimum/README.md b/tests/fixtures/roles/minimum/README.md
index 7737665..a1f530c 100644
--- a/tests/fixtures/roles/minimum/README.md
+++ b/tests/fixtures/roles/minimum/README.md
@@ -1,21 +1,20 @@
 <!-- BEGIN_ANSIBLE_DOCS -->
 # Ansible Role: minimum
----
 Test role with a minimum amount of metadata
 
 
 ## Requirements
----
+
 | Platform | Versions |
 | -------- | -------- |
 | Fedora | all |
 
 ## Role Arguments
----
+
 
 
 ### Entrypoint: main
----
+
 The main entry point for the minimum role.
 
 |Option|Description|Type|Required|Default|
@@ -26,11 +25,10 @@ The main entry point for the minimum role.
 
 
 ## Dependencies
----
 None.
 
 ## Example Playbook
----
+
 ```
 - hosts: all
   tasks:
@@ -42,11 +40,10 @@ None.
 ```
 
 ## License
----
+
 MIT
 
 ## Author and Project Information
----
 your name @ ansible-docs
 
 <!-- END_ANSIBLE_DOCS -->
diff --git a/tests/fixtures/roles/multiple_entrypoints/README.md b/tests/fixtures/roles/multiple_entrypoints/README.md
index f18a8f4..89342c8 100644
--- a/tests/fixtures/roles/multiple_entrypoints/README.md
+++ b/tests/fixtures/roles/multiple_entrypoints/README.md
@@ -1,21 +1,20 @@
 <!-- BEGIN_ANSIBLE_DOCS -->
 # Ansible Role: multiple_entrypoints
----
 Test role with a multiple_entrypoints amount of metadata
 
 
 ## Requirements
----
+
 | Platform | Versions |
 | -------- | -------- |
 | Fedora | all |
 
 ## Role Arguments
----
+
 
 
 ### Entrypoint: main
----
+
 The main entry point for the multiple_entrypoints role.
 
 |Option|Description|Type|Required|Default|
@@ -26,7 +25,7 @@ The main entry point for the multiple_entrypoints role.
 
 
 ### Entrypoint: second
----
+
 The second entry point for the multiple_entrypoints role.
 
 |Option|Description|Type|Required|Default|
@@ -37,11 +36,10 @@ The second entry point for the multiple_entrypoints role.
 
 
 ## Dependencies
----
 None.
 
 ## Example Playbook
----
+
 ```
 - hosts: all
   tasks:
@@ -54,11 +52,10 @@ None.
 ```
 
 ## License
----
+
 MIT
 
 ## Author and Project Information
----
 your name @ ansible-docs
 
 <!-- END_ANSIBLE_DOCS -->
diff --git a/tests/fixtures/roles/no_options/README.md b/tests/fixtures/roles/no_options/README.md
index 5cccadd..5d2fb5a 100644
--- a/tests/fixtures/roles/no_options/README.md
+++ b/tests/fixtures/roles/no_options/README.md
@@ -1,21 +1,20 @@
 <!-- BEGIN_ANSIBLE_DOCS -->
 # Ansible Role: no_options
----
 Test role with no options
 
 
 ## Requirements
----
+
 | Platform | Versions |
 | -------- | -------- |
 | Fedora | all |
 
 ## Role Arguments
----
+
 
 
 ### Entrypoint: main
----
+
 The main entry point for the no_options role.
 
 This entrypoint has no options.
@@ -23,11 +22,10 @@ This entrypoint has no options.
 
 
 ## Dependencies
----
 None.
 
 ## Example Playbook
----
+
 ```
 - hosts: all
   tasks:
@@ -38,11 +36,10 @@ None.
 ```
 
 ## License
----
+
 MIT
 
 ## Author and Project Information
----
 your name @ ansible-docs
 
 <!-- END_ANSIBLE_DOCS -->