{"id":16668960,"url":"https://github.com/mgaitan/sphinxcontrib-mermaid","last_synced_at":"2025-05-15T07:07:46.674Z","repository":{"id":39520524,"uuid":"61834797","full_name":"mgaitan/sphinxcontrib-mermaid","owner":"mgaitan","description":"Mermaid diagrams in yours sphinx powered docs","archived":false,"fork":false,"pushed_at":"2025-04-29T13:27:41.000Z","size":177,"stargazers_count":361,"open_issues_count":36,"forks_count":99,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-05-11T08:16:21.167Z","etag":null,"topics":["diagrams","sphinx-doc","sphinx-extension","sphinxcontrib","uml"],"latest_commit_sha":null,"homepage":"http://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mgaitan.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE.rst","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-06-23T20:28:57.000Z","updated_at":"2025-05-09T14:20:15.000Z","dependencies_parsed_at":"2023-01-29T19:15:56.927Z","dependency_job_id":"ccb5e72b-18da-401a-bc07-caf16d57b384","html_url":"https://github.com/mgaitan/sphinxcontrib-mermaid","commit_stats":{"total_commits":160,"total_committers":40,"mean_commits":4.0,"dds":0.575,"last_synced_commit":"ceddc68e62ff1f032e1314f471df52114ed31fd7"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgaitan%2Fsphinxcontrib-mermaid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgaitan%2Fsphinxcontrib-mermaid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgaitan%2Fsphinxcontrib-mermaid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgaitan%2Fsphinxcontrib-mermaid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mgaitan","download_url":"https://codeload.github.com/mgaitan/sphinxcontrib-mermaid/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254292043,"owners_count":22046426,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diagrams","sphinx-doc","sphinx-extension","sphinxcontrib","uml"],"created_at":"2024-10-12T11:28:24.838Z","updated_at":"2025-05-15T07:07:41.665Z","avatar_url":"https://github.com/mgaitan.png","language":"Python","funding_links":[],"categories":["Visualization"],"sub_categories":[],"readme":".. attention::\n\n   **Seeking for new maintainers**\n\n   `sphinxcontrib-mermaid` is actively seeking new maintainers. As the original creator, I’m no longer able to dedicate the time and attention needed. If you’re interested in contributing and helping to drive this project forward, please see `this issue \u003chttps://github.com/mgaitan/sphinxcontrib-mermaid/issues/148\u003e`_.\n\n\n------\n\n.. image:: https://github.com/mgaitan/sphinxcontrib-mermaid/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/mgaitan/sphinxcontrib-mermaid/actions/workflows/test.yml\n\n.. image:: https://img.shields.io/pypi/v/sphinxcontrib-mermaid\n   :target: https://pypi.org/project/sphinxcontrib-mermaid/\n\n.. image:: https://img.shields.io/pypi/dm/shbin\n   :target: https://libraries.io/pypi/sphinxcontrib-mermaid/\n\n\nThis extension allows you to embed `Mermaid \u003chttps://mermaid.js.org/\u003e`_ graphs in your\ndocuments, including general flowcharts, sequence diagrams, gantt diagrams and more.\n\nIt adds a directive to embed mermaid markup. For example::\n\n  .. mermaid::\n\n     sequenceDiagram\n        participant Alice\n        participant Bob\n        Alice-\u003eJohn: Hello John, how are you?\n        loop Healthcheck\n            John-\u003eJohn: Fight against hypochondria\n        end\n        Note right of John: Rational thoughts \u003cbr/\u003eprevail...\n        John--\u003eAlice: Great!\n        John-\u003eBob: How about you?\n        Bob--\u003eJohn: Jolly good!\n\n\nBy default, the HTML builder will simply render this as a ``div`` tag with\n``class=\"mermaid\"``, injecting the external javascript, css and initialization code to\nmake mermaid works.\n\nFor other builders (or if ``mermaid_output_format`` config variable is set differently), the extension\nwill use `mermaid-cli \u003chttps://github.com/mermaid-js/mermaid-cli\u003e`_ to render as\nto a PNG or SVG image, and then used in the proper code.\n\n\n.. mermaid::\n\n   sequenceDiagram\n      participant Alice\n      participant Bob\n      Alice-\u003eJohn: Hello John, how are you?\n      loop Healthcheck\n          John-\u003eJohn: Fight against hypochondria\n      end\n      Note right of John: Rational thoughts \u003cbr/\u003eprevail...\n      John--\u003eAlice: Great!\n      John-\u003eBob: How about you?\n      Bob--\u003eJohn: Jolly good!\n\n\nYou can also embed external mermaid files, by giving the file name as an\nargument to the directive and no additional content::\n\n   .. mermaid:: path/to/mermaid-gantt-code.mmd\n\nAs for all file references in Sphinx, if the filename is not absolute, it is\ntaken as relative to the source directory.\n\n\nIn addition, you can use mermaid to automatically generate a diagram to show the class inheritance using the directive ``autoclasstree``. It accepts one or more fully qualified\nnames to a class or a module. In the case of a module, all the class found will be included.\n\nOf course, these objects need to be importable to make its diagram.\n\nIf an optional attribute ``:full:`` is given, it will show the complete hierarchy of each class.\n\nThe option ``:namespace: \u003cvalue\u003e`` limits to the base classes that belongs to this namespace.\nMeanwhile, the flag ``:strict:`` only process the classes that are strictly defined in the given\nmodule (ignoring classes imported from other modules).\n\n\nFor example::\n\n    .. autoclasstree:: sphinx.util.DownloadFiles sphinx.util.ExtensionError\n       :full:\n\n.. autoclasstree:: sphinx.util.DownloadFiles sphinx.util.ExtensionError\n   :full:\n\n\nOr directly the module::\n\n    .. autoclasstree:: sphinx.util\n\n\n.. autoclasstree:: sphinx.util\n\n\nInstallation\n------------\n\nYou can install it using pip\n\n::\n\n    pip install sphinxcontrib-mermaid\n\nThen add ``sphinxcontrib.mermaid`` in ``extensions`` list of your project's ``conf.py``::\n\n    extensions = [\n        ...,\n        'sphinxcontrib.mermaid'\n    ]\n\n\nDirective options\n------------------\n\n``:name:``: determines the image's name (id) for HTML output.\n\n``:alt:``: determines the image's alternate text for HTML output.  If not given, the alternate text defaults to the mermaid code.\n\n``:align:``: determines the image's position. Valid options are ``'left'``, ``'center'``, ``'right'``\n\n``:caption:``: can be used to give a caption to the diagram.\n\n``:zoom:``: can be used to enable zooming the diagram. For a global config see ``mermaid_d3_zoom``` bellow. \n\n.. figure:: https://user-images.githubusercontent.com/16781833/228022911-c26d1e01-7f71-4ab7-bb33-ce53056f8343.gif\n   :align: center\n   \n   A preview after adding ``:zoom:`` option only to the first diagram example above:\n\n``:config:``: JSON to pass through to the `mermaid configuration \u003chttps://mermaid.js.org/config/configuration.html\u003e`_\n\n``:title:``: Title to pass through to the `mermaid configuration \u003chttps://mermaid.js.org/config/configuration.html\u003e`_\n\n\nConfig values\n-------------\n\n``mermaid_output_format``\n\n   The output format for Mermaid when building HTML files.  This must be either ``'raw'``\n   ``'png'`` or ``'svg'``; the default is ``'raw'``. ``mermaid-cli`` is required if it's not ``raw``\n\n``mermaid_use_local``\n\n   Optional path to a local installation of ``mermaid.esm.min.mjs``. By default, we will pull from jsdelivr.\n\n``mermaid_version``\n\n  The version of mermaid that will be used to parse ``raw`` output in HTML files. This should match a version available on https://www.jsdelivr.com/package/npm/mermaid.  The default is ``\"11.2.0\"``.\n\n.. versionchanged:: 0.7\n    The init code doesn't include the `\u003cscript\u003e` tag anymore. It's automatically added at build time.\n\n``mermaid_elk_use_local``\n\n   Optional path to a local installation of ``mermaid-layout-elk.esm.min.mjs``. By default, we will pull from jsdelivr.\n\n``mermaid_include_elk``\n\n  The version of mermaid ELK renderer that will be used. The default is ``\"0.1.4\"``. Leave blank to disable ELK layout.\n\n``d3_use_local``\n\n   Optional path to a local installation of ``d3.min.js``. By default, we will pull from jsdelivr.\n\n``d3_version``\n\n  The version of d3 that will be used to provide zoom functionality on mermaid graphs.  The default is ``\"7.9.0\"``.\n\n``mermaid_init_js``\n\n  Mermaid initialization code. The Default initialization is set to\n\n    mermaid.initialize({ startOnLoad: true})\n\n\n.. versionchanged:: 0.7\n    The init code doesn't include the `\u003cscript\u003e` tag anymore. It's automatically added at build time.\n\n\n``mermaid_cmd``\n\n   The command name with which to invoke ``mermaid-cli`` program.\n   The default is ``'mmdc'``; you may need to set this to a full path if it's not in the executable search path.\n   If a string is specified, it is split using `shlex.split` to support multi-word commands.\n   To avoid splitting, a list of strings can be specified.\n   Examples::\n\n      mermaid_cmd = 'npx mmdc'\n      mermeid_cmd = ['npx', '--no-install', 'mmdc']\n\n``mermaid_cmd_shell``\n\n   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.\n\n``mermaid_params``\n\n   For individual parameters, a list of parameters can be added. Refer to `\u003chttps://github.com/mermaid-js/mermaid-cli#usage\u003e`_.\n   Examples::\n\n      mermaid_params = ['--theme', 'forest', '--width', '600', '--backgroundColor', 'transparent']\n\n   This will render the mermaid diagram with theme forest, 600px width and transparent background.\n\n``mermaid_sequence_config``\n\n    Allows overriding the sequence diagram configuration. It could be useful to increase the width between actors. It **needs to be a json file**\n    Check options in the `documentation \u003chttps://mermaid-js.github.io/mermaid/#/mermaidAPI?id=configuration\u003e`_\n\n``mermaid_verbose``\n\n    Use the verbose mode when call mermaid-cli, and show its output in the building\n    process.\n\n``mermaid_pdfcrop``\n\n    If using latex output, it might be useful to crop the pdf just to the needed space. For this, ``pdfcrop`` can be used.\n    State binary name to use this extra function.\n\n``mermaid_d3_zoom``\n\n    Enables zooming in all the generated Mermaid diagrams.\n\n\nMarkdown support\n----------------\n\nYou can include Mermaid diagrams in your Markdown documents in Sphinx.\nYou just need to setup the `markdown support in Sphinx \u003chttps://www.sphinx-doc.org/en/master/usage/markdown.html\u003e`_ via\n`myst-parser \u003chttps://myst-parser.readthedocs.io/\u003e`_\n. See a `minimal configuration from the tests \u003chttps://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/tests/roots/test-markdown/conf.py\u003e`_\n\nThen in your `.md` documents include a code block as in reStructuredTexts::\n\n\n ```{mermaid}\n\n     sequenceDiagram\n       participant Alice\n       participant Bob\n       Alice-\u003eJohn: Hello John, how are you?\n ```\n\nFor GitHub cross-support, you can omit the curly braces and configure myst to use the `mermaid` code block as a myst directive. For example, in `conf.py`::\n\n    myst_fence_as_directive = [\"mermaid\"]\n\nBuilding PDFs on readthedocs.io\n-----------------------------------\n\nIn order to have Mermaid diagrams build properly in PDFs generated on readthedocs.io, you will need a few extra configurations.  \n\n1. In your ``.readthedocs.yaml`` file (which should be in the root of your repository) include a ``post-install`` command to install the Mermaid CLI: ::\n\n    build:\n      os: ubuntu-20.04\n      tools:\n        python: \"3.8\"\n        nodejs: \"16\"\n      jobs:\n        post_install:\n          - npm install -g @mermaid-js/mermaid-cli\n\n 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: ::\n\n    # .readthedocs.yaml\n    # Read the Docs configuration file\n    # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details\n\n    # Required\n    version: 2\n\n    # Set the version of Python and other tools you might need\n    build:\n      os: ubuntu-20.04\n      apt_packages:\n        - libasound2\n      tools:\n        python: \"3.8\"\n        nodejs: \"16\"\n      jobs:\n        post_install:\n          - npm install -g @mermaid-js/mermaid-cli\n\n    # Build documentation in the docs/ directory with Sphinx\n    sphinx:\n       configuration: docs/conf.py\n\n    # If using Sphinx, optionally build your docs in additional formats such as PDF\n    formats:\n      - epub\n      - pdf\n\n    python:\n       install:\n       - requirements: docs/requirements.txt\n\n2. In your documentation directory add file ``puppeteer-config.json`` with contents: ::\n\n    {\n      \"args\": [\"--no-sandbox\"]\n    }\n   \n\n3. In your documentation ``conf.py`` file, add: ::\n\n    mermaid_params = ['-p' 'puppeteer-config.json']\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgaitan%2Fsphinxcontrib-mermaid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmgaitan%2Fsphinxcontrib-mermaid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgaitan%2Fsphinxcontrib-mermaid/lists"}