========
Mermaid
========

If you use `sphinxcontrib-mermaid <https://github.com/mgaitan/sphinxcontrib-mermaid>`_
to generate flowcharts or diagrams, and you output the diagrams in "raw" format,
they will automatically adapt to this theme's light or dark mode.

To use this feature, you'll need to install `sphinxcontrib-mermaid`_ and add it to your
list of extensions in ``conf.py``:

.. code-block:: python

    # conf.py
    extensions = [
        ...,
        "sphinxcontrib.mermaid",
    ]

This will enable the ``.. mermaid::`` directive. For example:

.. begin-example-mermaid
.. mermaid::

    gitGraph:
        commit
        branch newbranch
        checkout newbranch
        commit id:"1111"
        commit tag:"test"
        checkout main
        commit type: HIGHLIGHT
        commit
        merge newbranch
        commit
        branch b2
        commit
.. end-example-mermaid

is generated by the following code:

.. include:: ./mermaid.rst
    :start-after: begin-example-mermaid
    :end-before: .. end-example-mermaid
    :code: rst
    :class: highlight

See the `Mermaid documentation <https://mermaid.js.org/syntax/examples>`__ for additional examples.