{"id":2776,"library":"sphinxcontrib-mermaid","title":"Sphinxcontrib Mermaid","description":"Sphinxcontrib Mermaid (version 2.0.1) is a Sphinx extension that enables embedding Mermaid.js diagrams directly into reStructuredText or Markdown documentation. It allows authors to create various diagrams like flowcharts, sequence diagrams, class diagrams, and Gantt charts using a simple text-based syntax. This approach ensures diagrams are version-controlled, easy to maintain, and rendered consistently with the Sphinx theme. The library is actively maintained, supports Python >=3.10, and is distributed via PyPI.","status":"active","version":"2.0.1","language":"python","source_language":"en","source_url":"https://github.com/mgaitan/sphinxcontrib-mermaid","tags":["Sphinx","documentation","diagrams","Mermaid","flowcharts","sequence diagrams","developer tools"],"install":[{"cmd":"pip install sphinxcontrib-mermaid","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core documentation generator, this is a Sphinx extension.","package":"Sphinx"},{"reason":"Required for rendering Mermaid diagrams to image formats (PNG/SVG) and for PDF builds. Must be installed via npm.","package":"mermaid-cli","optional":true},{"reason":"Required for embedding Mermaid diagrams within Markdown files in Sphinx projects.","package":"myst-parser","optional":true}],"imports":[{"note":"Add 'sphinxcontrib.mermaid' to the 'extensions' list in your project's conf.py to enable the directive.","symbol":"sphinxcontrib.mermaid","correct":"extensions = ['sphinxcontrib.mermaid']"}],"quickstart":{"code":"# conf.py\nimport os\nimport sys\nsys.path.insert(0, os.path.abspath('.'))\n\nproject = 'My Sphinx Project'\ncopyright = '2026, Your Name'\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinxcontrib.mermaid',\n]\n\n# Optional: configure mermaid output for non-raw formats (requires mermaid-cli)\n# mermaid_output_format = 'svg' # or 'png'\n# mermaid_cmd = 'npx mmdc' # if mmdc is in node_modules/.bin or globally installed\n\n# Optional: pin mermaid.js version\n# mermaid_version = \"11.12.1\"\n\n# index.rst (or any .rst file)\n# Here's a simple flowchart:\n#\n# .. mermaid::\n#    graph TD\n#        A[Start] --> B{Decision};\n#        B -->|One| C[Process 1];\n#        B -->|Two| D[Process 2];\n#        C --> E[End];\n#        D --> E;\n#\n# And a sequence diagram:\n#\n# .. mermaid::\n#    sequenceDiagram\n#        participant Alice\n#        participant Bob\n#        Alice->>Bob: Hello Bob, how are you?\n#        alt healthy\n#            Bob->>Alice: Great!\n#        else unwell\n#            Bob->>Alice: Not so good :(\n#        end\n#        Alice->>Bob: Ok, bye!","lang":"python","description":"After installing the package, add 'sphinxcontrib.mermaid' to your `extensions` list in `conf.py`. Then, use the `.. mermaid::` directive in your reStructuredText or Markdown files to embed Mermaid code. For image output (SVG/PNG) or PDF builds, `mermaid-cli` must also be installed via npm."},"warnings":[{"fix":"Install `mermaid-cli` globally or locally via npm (`npm install -g @mermaid-js/mermaid-cli`) and optionally configure `mermaid_cmd` in `conf.py` (e.g., `mermaid_cmd = 'npx mmdc'`).","message":"For non-raw HTML output (PNG, SVG) or when building PDFs, `mermaid-cli` (an npm package) must be installed and accessible. Without it, image rendering will fail. The `mermaid_cmd` configuration option may be needed to specify its path.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add `mermaid_output_format = 'svg'` (or 'png') to your `conf.py`. Remember this also requires `mermaid-cli`.","message":"The default `mermaid_output_format` is 'raw', which renders Mermaid directly in HTML via JavaScript. If you need static images (e.g., for PDF builds or certain HTML themes), you must explicitly set `mermaid_output_format` to 'svg' or 'png' in `conf.py`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Resolve conflicts by adding `nbsphinx_requirejs_path = ''` or `jupyter_sphinx_require_url = ''` to your `conf.py` as appropriate.","message":"Known `requirejs` conflicts exist when using `sphinxcontrib-mermaid` alongside extensions like `nbsphinx` or `jupyter-sphinx`, leading to JavaScript errors where Mermaid may not load.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor the GitHub repository for updates on maintenance status and consider contributing if possible.","message":"The project is actively seeking new maintainers, which could impact future development and support.","severity":"deprecated","affected_versions":"2.0.1 onwards"}],"env_vars":null,"search_vec":"'2.0.1':6 '3.10':70 'activ':66 'allow':23 'approach':46 'author':24 'base':43 'chart':37 'class':33 'consist':58 'control':52 'creat':26 'develop':83 'diagram':15,28,32,34,48,78,82 'direct':16 'distribut':73 'document':21,77 'easi':53 'embed':13 'enabl':12 'ensur':47 'extens':10 'flowchart':30,80 'gantt':36 'librari':64 'like':29 'maintain':55,67 'markdown':20 'mermaid':2,4,79 'mermaid.js':14 'pypi':75 'python':69 'render':57 'restructuredtext':18 'sequenc':31,81 'simpl':40 'sphinx':9,61,76 'sphinxcontrib':1,3 'support':68 'syntax':44 'text':42 'text-bas':41 'theme':62 'tool':84 'use':38 'various':27 'version':5,51 'version-control':50 'via':74","created_at":"2026-04-11T01:42:19.362295+00:00","updated_at":"2026-04-16T22:06:30.455781+00:00","problems":{"verify_error":"no import statement found"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.1.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/mgaitan/sphinxcontrib-mermaid","docs":null,"changelog":"https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/CHANGELOG.md","pypi":"https://pypi.org/project/sphinxcontrib-mermaid/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-05","install_tag":null}}