1 files changed, 104 insertions, 0 deletions
diff --git a/tools/moztreedocs/docs/mermaid-integration.rst b/tools/moztreedocs/docs/mermaid-integration.rst
new file mode 100644
index 0000000000..ec0da3dd74
--- /dev/null
+++ b/tools/moztreedocs/docs/mermaid-integration.rst
@@ -0,0 +1,104 @@
+Mermaid Integration
+===================
+
+Mermaid is a tool that lets you generate flow charts, sequence diagrams, gantt
+charts, class diagrams and vcs graphs from a simple markup language. This
+allows charts and diagrams to be embedded and edited directly in the
+documentation source files rather than creating them as images using some
+external tool and checking the images into the tree.
+
+To add a diagram, simply put something like this into your page:
+
+.. These two examples come from the upstream website (https://mermaid-js.github.io/mermaid/#/)
+
+.. code-block:: rst
+    :caption: .rst
+
+    .. mermaid::
+
+        graph TD;
+            A-->B;
+            A-->C;
+            B-->D;
+            C-->D;
+
+.. code-block:: md
+    :caption: .md
+
+    ```{mermaid}
+    graph TD;
+        A-->B;
+        A-->C;
+        B-->D;
+        C-->D;
+    ```
+
+The result will be:
+
+.. mermaid::
+
+     graph TD;
+         A-->B;
+         A-->C;
+         B-->D;
+         C-->D;
+
+Or
+
+.. code-block:: rst
+    :caption: .rst
+
+    .. mermaid::
+
+         sequenceDiagram
+             participant Alice
+             participant Bob
+             Alice->>John: Hello John, how are you?
+             loop Healthcheck
+                 John->>John: Fight against hypochondria
+             end
+             Note right of John: Rational thoughts <br/>prevail!
+             John-->>Alice: Great!
+             John->>Bob: How about you?
+             Bob-->>John: Jolly good!
+
+.. code-block:: markdown
+    :caption: .md
+
+    ```{mermaid}
+    sequenceDiagram
+        participant Alice
+        participant Bob
+        Alice->>John: Hello John, how are you?
+        loop Healthcheck
+            John->>John: Fight against hypochondria
+        end
+        Note right of John: Rational thoughts <br/>prevail!
+        John-->>Alice: Great!
+        John->>Bob: How about you?
+        Bob-->>John: Jolly good!
+    ```
+
+
+
+will show:
+
+.. mermaid::
+
+     sequenceDiagram
+         participant Alice
+         participant Bob
+         Alice->>John: Hello John, how are you?
+         loop Healthcheck
+             John->>John: Fight against hypochondria
+         end
+         Note right of John: Rational thoughts <br/>prevail!
+         John-->>Alice: Great!
+         John->>Bob: How about you?
+         Bob-->>John: Jolly good!
+
+
+See `Mermaid's official <https://mermaid-js.github.io/mermaid/#/>`__ docs for
+more details on the syntax, and use the
+`Mermaid Live Editor <https://mermaidjs.github.io/mermaid-live-editor/>`__ to
+experiment with creating your own diagrams.