diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md
index ed60a1b3ff4..62a90726eda 100644
--- a/docs/diagrams/README.md
+++ b/docs/diagrams/README.md
@@ -18,6 +18,26 @@ This is a "diagrams playground" folder and you don't have to use this. Instead,
        B->>-A: Greetings!
 ```
 
+To create diagrams in a markdown file, you can use the same syntax as above but wrap it in triple backticks (used for code blocks) with `{eval-rst}` as the language identifier, e.g.:
+
+````markdown
+```{eval-rst}
+.. kroki::
+   :type: mermaid
+   :caption: Diagram
+
+   %% The message sending flow as implemented for M1 (Oct 2021) federation
+   sequenceDiagram
+       actor A as Alice
+       participant B as Backend
+
+       Note over A,B: send message
+       %% this is a code-comment not visible
+       A->>+B: Hello!
+       B->>-A: Greetings!!!!
+```
+````
+
 For more information, see syntax on https://mermaid-js.github.io/mermaid/#/sequenceDiagram
 
 # Playground mermaid setup and further links