.\" Man page generated from reStructuredText.
.
.TH "SPHINXCONTRIB-MERMAID" "3" "Aug 11, 2022" "" "sphinxcontrib-mermaid"
.SH NAME
sphinxcontrib-mermaid \- sphinxcontrib-mermaid documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
\fI\%\fP
.sp
This extension allows you to embed \fI\%Mermaid\fP graphs in your
documents, including general flowcharts, sequence and gantt diagrams.
.sp
It adds a directive to embed mermaid markup. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.. 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!
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
By default, the HTML builder will simply render this as a \fBdiv\fP tag with
\fBclass="mermaid"\fP, injecting the external javascript, css and initialization code to
make mermaid works.
.sp
For other builders (or if \fBmermaid_output_format\fP config variable is set differently), the extension
will use \fI\%mermaid\-cli\fP to render as
to a PNG or SVG image, and then used in the proper code.
[graph]
.sp
You can also embed external mermaid files, by giving the file name as an
argument to the directive and no additional content:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.. mermaid:: path/to/mermaid\-gantt\-code.mmd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As for all file references in Sphinx, if the filename is not absolute, it is
taken as relative to the source directory.
.sp
In addition, you can use mermaid to automatically generate a diagram to show the class inheritance using the directive \fBautoclasstree\fP\&. It accepts one or more fully qualified
names to a class or a module. In the case of a module, all the class found will be included.
.sp
Of course, these objects need to be importable to make its diagram.
.sp
If an optional attribute \fB:full:\fP is given, it will show the complete hierarchy of each class.
.sp
The option \fB:namespace: <value>\fP limits to the base classes that belongs to this namespace.
Meanwhile, the flag \fB:strict:\fP only process the classes that are strictly defined in the given
module (ignoring classes imported from other modules).
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.. autoclasstree:: sphinx.util.SphinxParallelError sphinx.util.ExtensionError
   :full:
.ft P
.fi
.UNINDENT
.UNINDENT
[graph]
.sp
Or directly the module:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.. autoclasstree:: sphinx.util
.ft P
.fi
.UNINDENT
.UNINDENT
[graph].SH INSTALLATION
.sp
You can install it using pip
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pip install sphinxcontrib\-mermaid
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then add \fBsphinxcontrib.mermaid\fP in \fBextensions\fP list of your project\(aqs \fBconf.py\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extensions = [
    ...,
    \(aqsphinxcontrib.mermaid\(aq
]
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DIRECTIVE OPTIONS
.sp
\fB:alt:\fP: determines the image\(aqs alternate text for HTML output.  If not given, the alternate text defaults to the mermaid code.
.sp
\fB:align:\fP: determines the image\(aqs position. Valid options are \fB\(aqleft\(aq\fP, \fB\(aqcenter\(aq\fP, \fB\(aqright\(aq\fP
.sp
\fB:caption:\fP: can be used to give a caption to the diagram.
.SH CONFIG VALUES
.sp
\fBmermaid_output_format\fP
.INDENT 0.0
.INDENT 3.5
The output format for Mermaid when building HTML files.  This must be either \fB\(aqraw\(aq\fP
\fB\(aqpng\(aq\fP or \fB\(aqsvg\(aq\fP; the default is \fB\(aqraw\(aq\fP\&. \fBmermaid\-cli\fP is required if it\(aqs not \fBraw\fP
.UNINDENT
.UNINDENT
.sp
\fBmermaid_version\fP
.INDENT 0.0
.INDENT 3.5
The version of mermaid that will be used to parse \fBraw\fP output in HTML files. This should match a version available on \fI\%https://unpkg.com/browse/mermaid/\fP\&. The default is \fB"latest"\fP\&.
.sp
If it\(aqs set to \fB""\fP, the lib won\(aqt be automatically included from the CDN service and you\(aqll need to add it as a local
file in \fBhtml_js_files\fP\&. For instance, if you download the lib to \fI_static/js/mermaid.js\fP, in \fBconf.py\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
html_js_files = [
   \(aqjs/mermaid.js\(aq,
]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBmermaid_init_js\fP
.INDENT 0.0
.INDENT 3.5
Mermaid initilizaction code. Default to \fB"mermaid.initialize({startOnLoad:true});"\fP\&.
.UNINDENT
.UNINDENT
.sp
Changed in version 0.7: The init code doesn\(aqt include the \fI<script>\fP tag anymore. It\(aqs automatically added at build time.

.sp
\fBmermaid_cmd\fP
.INDENT 0.0
.INDENT 3.5
The command name with which to invoke \fBmermaid\-cli\fP program.  The default is \fB\(aqmmdc\(aq\fP; you may need to set this to a full path if it\(aqs not in the executable search path.
.UNINDENT
.UNINDENT
.sp
\fBmermaid_cmd_shell\fP
.INDENT 0.0
.INDENT 3.5
When set to true, the \fBshell=True\fP argument will be passed the process execution command.  This allows commands other than binary executables to be executed on Windows.  The default is false.
.UNINDENT
.UNINDENT
.sp
\fBmermaid_params\fP
.INDENT 0.0
.INDENT 3.5
For individual parameters, a list of parameters can be added. Refer to \fI\%https://github.com/mermaidjs/mermaid.cli#options\fP\&.
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mermaid_params = [\(aq\-\-theme\(aq, \(aqforest\(aq, \(aq\-\-width\(aq, \(aq600\(aq, \(aq\-\-backgroundColor\(aq, \(aqtransparent\(aq]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will render the mermaid diagram with theme forest, 600px width and transparent background.
.UNINDENT
.UNINDENT
.sp
\fBmermaid_sequence_config\fP
.INDENT 0.0
.INDENT 3.5
Allows overriding the sequence diagram configuration. It could be useful to increase the width between actors. It \fBneeds to be a json file\fP
Check options in the \fI\%documentation\fP
.UNINDENT
.UNINDENT
.sp
\fBmermaid_verbose\fP
.INDENT 0.0
.INDENT 3.5
Use the verbose mode when call mermaid\-cli, and show its output in the building
process.
.UNINDENT
.UNINDENT
.sp
\fBmermaid_pdfcrop\fP
.INDENT 0.0
.INDENT 3.5
If using latex output, it might be useful to crop the pdf just to the needed space. For this, \fBpdfcrop\fP can be used.
State binary name to use this extra function.
.UNINDENT
.UNINDENT
.SH MARKDOWN SUPPORT
.sp
You can include Mermaid diagrams in your Markdown documents in Sphinx.
You just need to setup the \fI\%markdown support in Sphinx\fP via
\fI\%myst\-parser\fP
\&. See a \fI\%minimal configuration from the tests\fP
.sp
Then in your \fI\&.md\fP documents include a code block as in reStructuredTexts:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\(ga\(ga\(ga{mermaid}

    sequenceDiagram
      participant Alice
      participant Bob
      Alice\->John: Hello John, how are you?
\(ga\(ga\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
genindex
.IP \(bu 2
modindex
.IP \(bu 2
search
.UNINDENT
.SH AUTHOR
Martín Gaitán
.SH COPYRIGHT
2017-2022, Martín Gaitán
.\" Generated by docutils manpage writer.
.