Ubuntu Manpages

sphinxcontrib-mermaid

sphinxcontrib-mermaid documentation This extension allows you to embed Mermaid graphs in your documents, including general flowcharts, sequence diagrams, gantt diagrams and more. It adds a directive …

:alt:: determines the image's alternate text for HTML output. If not given, the alternate text defaults to the mermaid code.

:align:: determines the image's position. Valid options are 'left', 'center', 'right'

:caption:: can be used to give a caption to the diagram.

:zoom:: can be used to enable zooming the diagram. For a global config see mermaid_d3_zoom` below.

[image] A preview after adding :zoom: option only to the first diagram example above:.UNINDENT

mermaid_output_format

The output format for Mermaid when building HTML files. This must be either 'raw' 'png' or 'svg'; the default is 'raw'. mermaid-cli is required if it's not raw


mermaid_version

The version of mermaid that will be used to parse raw output in HTML files. This should match a version available on https://unpkg.com/browse/mermaid/. The default is "10.2.0". If you need a newer version, you'll need to add the custom initialization. See below.

If it's set to "", the lib won't be automatically included from the CDN service and you'll need to add it as a local file in html_js_files. For instance, if you download the lib to _static/js/mermaid.js, in conf.py:

html_js_files = [
   'js/mermaid.js',
]




mermaid_init_js

Mermaid initilizaction code. Default to "mermaid.initialize({startOnLoad:true});".


Changed in version 0.7: The init code doesn't include the <script> tag anymore. It's automatically added at build time.

mermaid_cmd

The command name with which to invoke mermaid-cli program. The default is 'mmdc'; you may need to set this to a full path if it's not in the executable search path.


mermaid_cmd_shell

When set to true, the shell=True argument will be passed the process execution command. This allows commands other than binary executables to be executed on Windows. The default is false.


mermaid_params

For individual parameters, a list of parameters can be added. Refer to https://github.com/mermaidjs/mermaid.cli#options. Examples: 

mermaid_params = ['--theme', 'forest', '--width', '600', '--backgroundColor', 'transparent']


This will render the mermaid diagram with theme forest, 600px width and transparent background.



mermaid_sequence_config

Allows overriding the sequence diagram configuration. It could be useful to increase the width between actors. It needs to be a json file Check options in the documentation


mermaid_verbose

Use the verbose mode when call mermaid-cli, and show its output in the building process.


mermaid_pdfcrop

If using latex output, it might be useful to crop the pdf just to the needed space. For this, pdfcrop can be used. State binary name to use this extra function.


mermaid_d3_zoom

Enables zooming in all the generated Mermaid diagrams.


You can include Mermaid diagrams in your Markdown documents in Sphinx. You just need to setup the markdown support in Sphinx via myst-parser . See a minimal configuration from the tests

Then in your .md documents include a code block as in reStructuredTexts:

```{mermaid}
    sequenceDiagram
      participant Alice
      participant Bob
      Alice->John: Hello John, how are you?
```


In order to have Mermaid diagrams build properly in PDFs generated on readthedocs.io, you will need a few extra configurations.

1.
In your .readthedocs.yaml file (which should be in the root of your repository) include a post-install command to install the Mermaid CLI:

build:
  os: ubuntu-20.04
  tools:
    python: "3.8"
    nodejs: "16"
  jobs:
    post_install:
      - npm install -g @mermaid-js/mermaid-cli



Note that if you previously did not have a .readthedocs.yaml file, you will also need to specify all targets you wish to build and other basic configuration options. A minimal example of a complete file is: 

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the version of Python and other tools you might need
build:
  os: ubuntu-20.04
  tools:
    python: "3.8"
    nodejs: "16"
  jobs:
    post_install:
      - npm install -g @mermaid-js/mermaid-cli
# Build documentation in the docs/ directory with Sphinx
sphinx:
   configuration: docs/conf.py
# If using Sphinx, optionally build your docs in additional formats such as PDF
formats:
  - epub
  - pdf
python:
   install:
   - requirements: docs/requirements.txt




2.
In your documentation directory add file puppeteer-config.json with contents:

{
  "args": ["--no-sandbox"]
}


3.
In your documentation conf.py file, add:

mermaid_params = ['-p' 'puppeteer-config.json']



[graph].INDENT 0.0

  • Index
  • Module Index
  • Search Page


Martín Gaitán

2017-2024, Martín Gaitán